gitee地址: smart-doc
效果图
如何集成smart-doc
1.在pom.xml文件添加
<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>1.0.3</version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>API文档</projectName> </configuration> <executions> <execution> <!--如果不需要在执行编译时启动smart-doc,则将phase注释掉--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin>
2.resources目录下新增smart-doc.json文件
{ "serverUrl": "http://127.0.0.1:8080/api-demo/", //设置服务器地址,非必须 "isStrict": false, //是否开启严格模式 "allInOne": true, //是否将文档合并到一个文件中,一般推荐为true "coverOld": true, //是否覆盖旧的文件,主要用于mardown文件覆盖 "packageFilters": "",//controller包过滤,多个包用英文逗号隔开 "outPath": "src/main/resources/static/doc", //指定文档的输出路径 "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用 "projectName": "CMP基础服务API文档",//配置自己的项目名称 "showAuthor":true, //是否显示接口作者名称,默认是true,不想显示可关闭 "dataDictionaries": [ //配置数据字典,没有需求可以不设置 { "title": "状态字典", "enumClassName": "cn.xx.docStatusEnum", "codeField": "key", "descField": "value" } ] }
3.maven运行,将会扫描controller生成文档,文档地址在上面定义的"outPath"参数
//生成html mvn -Dfile.encoding=UTF-8 smart-doc:html //生成markdown mvn -Dfile.encoding=UTF-8 smart-doc:markdown //生成adoc mvn -Dfile.encoding=UTF-8 smart-doc:adoc //生成postman json数据 mvn -Dfile.encoding=UTF-8 smart-doc:postman
4.smart-doc相关注解
tag名称 | 描述 |
@ignore | ignore tag用于过滤请求参数对象上的某个字段,设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看忽略响应字段,如果ignore加到方法上,则接口方法不会输出到文档。 |
@required | 如果你没有使用JSR303参数验证规范实现的方式来标注字段,就可以使用@required去标注请求参数对象的字段,标注smart-doc在输出参数列表时会设置为true。 |
@mock | 从smart-doc 1.8.0开始,mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档。 |