TongchengOpenSource / smart-doc

Smart-doc is a java restful api document generation tool. Smart-doc is based on interface source code analysis to generate interface documentation, completely zero-injection.
https://smart-doc-group.github.io/#/
Apache License 2.0
1.42k stars 277 forks source link

Add a custom tag to control whether an interface is online or not. #353

Open tianmingxing opened 2 years ago

tianmingxing commented 2 years ago

Summary(关于这个pr的描述)

You can add custom tags to the interface comments to indicate the online status of the interface. By default, it's set to be online; otherwise, use the specified status. 可以在接口注释上打上自定义标签,指明这个接口的上线状态,缺省是默认上线的,反之采用指定的状态。

Basic example(pr的用例)

/**
 * 
 * @release false
 */
@GetMapping("/test")
void test(){}

Motivation(提出这个pr目的)

During the version development process, documentation needs to be generated for the testing staff to write test cases, and other project team members will also review it. If we cannot effectively identify the release status of an interface, it could easily increase communication costs and even lead to misuse by consumers.

在版本开发过程中,需要生成文档供测试同事写用例,其它项目组成员也会查看,如果不能有效标识接口的发布状态,则容易增加沟通成本,甚至调用方误用。

netdied commented 2 years ago

use Deprecated

tianmingxing commented 2 years ago

文档需要生成出来给别人看

tianmingxing commented 2 years ago

@shalousun 关于这个需求,我看只能通过增加自定义标签来解决,不知你有没有其它更好的方式,讨论一下吧!

shalousun commented 2 years ago

@shalousun 关于这个需求,我看只能通过增加自定义标签来解决,不知你有没有其它更好的方式,讨论一下吧!

用标签可以,只是这种接口状态在文档中没有状态显示。单独起一个标签也不是很好,有人就反映过smart-doc文档过长,就是整个一个方法的文档成列过长,没增加一个子级标签就会导致文档看起来更长,但是也没有专业的前端搞。可能就是smart-doc仅仅提供原始数据,后面让torna那边去搞,smart-doc的内置文档模板不在更改

tianmingxing commented 2 years ago

@shalousun 关于这个需求,我看只能通过增加自定义标签来解决,不知你有没有其它更好的方式,讨论一下吧!

用标签可以,只是这种接口状态在文档中没有状态显示。单独起一个标签也不是很好,有人就反映过smart-doc文档过长,就是整个一个方法的文档成列过长,没增加一个子级标签就会导致文档看起来更长,但是也没有专业的前端搞。可能就是smart-doc仅仅提供原始数据,后面让torna那边去搞,smart-doc的内置文档模板不在更改

目前smart-doc生成的HTML文档是我们需要的,因为我们需要这种接口和描述文档结合在一起的形式。如果内置文档模板不改,那么是否能让我们提供自己的模板?

shalousun commented 2 years ago

@shalousun 关于这个需求,我看只能通过增加自定义标签来解决,不知你有没有其它更好的方式,讨论一下吧!

用标签可以,只是这种接口状态在文档中没有状态显示。单独起一个标签也不是很好,有人就反映过smart-doc文档过长,就是整个一个方法的文档成列过长,没增加一个子级标签就会导致文档看起来更长,但是也没有专业的前端搞。可能就是smart-doc仅仅提供原始数据,后面让torna那边去搞,smart-doc的内置文档模板不在更改

目前smart-doc生成的HTML文档是我们需要的,因为我们需要这种接口和描述文档结合在一起的形式。如果内置文档模板不改,那么是否能让我们提供自己的模板?

这个也不是绝对的不改,其实你们模板设计比较通用也可以提供作为社区模板,我们当前主要是没人去设计和搞这些模板。 另外一个这个接口状态,我看了下别的软件也不仅仅是上线和开发中的状态