springboot项目使用smart-doc生成api html文档
原创 stackover 发表于:2020-03-18 14:05:52
  阅读 :358   收藏   编辑

gitee地址: smart-doc

效果图

1

如何集成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名称描述
@ignoreignore tag用于过滤请求参数对象上的某个字段,设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看忽略响应字段,如果ignore加到方法上,则接口方法不会输出到文档。
@required如果你没有使用JSR303参数验证规范实现的方式来标注字段,就可以使用@required去标注请求参数对象的字段,标注smart-doc在输出参数列表时会设置为true。
@mock从smart-doc 1.8.0开始,mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档。