官方文档

放在了Gitee的WIKI中

https://gitee.com/smart-doc-team/smart-doc/wikis/HOME

Maven安装

加上Maven插件即可，不用其他依赖

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.2.8</version>
    <configuration>
        <!--指定smart-doc使用的配置文件路径-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>fan-blog-doc</projectName>
    </configuration>    
    <executions>
        <execution>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>openapi</goal>
            </goals>
        </execution>
    </executions>
</plugin>

然后就可以在项目中使用改插件生成文档

配置

根据配置的文件路径创建JSON文件，示例

{
  "serverUrl": "http://localhost:8000", //指定后端服务访问地址
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看
  "isStrict": false, //是否开启严格模式
  "allInOne": true, //是否将文档合并到一个文件中
  "createDebugPage": true, //是否创建可以测试的html页面
  "style": "xt256", //基于highlight.js的代码高设置
  "projectName": "接口文档测试", //配置自己的项目名称
  "showAuthor": true, //是否显示接口作者名称
  "allInOneDocFileName": "index.html" //自定义设置输出文档名称
}

更多详细配置看文档的Maven模块下

推送到Torna

Torna官网，详情见开发文档

在配置文件中指定相关数据即可

{
  "serverUrl": "http://localhost:8000", //指定后端服务访问地址
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看
  "isStrict": false, //是否开启严格模式
  "allInOne": true, //是否将文档合并到一个文件中
  "createDebugPage": true, //是否创建可以测试的html页面
  "style": "xt256", //基于highlight.js的代码高设置
  "projectName": "接口文档测试", //配置自己的项目名称
  "showAuthor": true, //是否显示接口作者名称
  "allInOneDocFileName": "index.html", //自定义设置输出文档名称
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "appKey": "20211104905771723889049600",// torna平台对接appKey,, @since 2.0.9
  "appToken": "f347ea5e57c640ac88f63486479e029b", //torna平台appToken,@since 2.0.9
  "secret": "nEpwXU##mBgwdra*BN6r,1TVxjv@5a8#",//torna平台secret，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "debugEnvUrl":"http://localhost:8000" //torna
}

注释使用

在类上加注释

/**
 * 测试接口
 *
 * @author FanJun
 * @author Wang
 */

在接口上加注释

 /**  
   * 接口标题
   *
   * @param req 参数
   * @return 返沪统一响应对象
   * @apiNote 接口描述
   */

注意：在方法上加了作者后，该接口的作者只有方法上的，类上的作者名不再显示

删除接口

不想删除代码的方式

请求方式

主要取决与接口是否使用了@RequestBody注解，如果使用了就是application/json; charset=utf-8，否则application/x-www-form-urlencoded;charset=utf-8

使用总结

接口作者

统一类方式：该类下没有使用@author的接口都会使用类上的作者

/**
 * 分类相关接口
 *
 * @author Fan
 */
@RestController
public class CategoryController {
}

单个接口指定方式：在文档中只会出现指定的名字，统一的指定不会出现

/**
 * 获取分类列表（管理）
 *
 * @author Zhang
 */
@PostMapping("/manage/category/list")
public Result<List<Category>> list() {
}

多作者指定方式：

/**
 * 获取分类列表（管理）
 *
 * @author Fan
 * @author Zhang
 */
@PostMapping("/manage/category/list")
public Result<List<Category>> list() {
}

接口废弃

在文档上用线划掉，表示废弃

/**
 * 获取分类列表（管理）
 *
 * @deprecated
 */
@Deprecated
@PostMapping("/manage/category/list")
public Result<List<Category>> list() {
}

接口删除

不会在文档上出现

/**
 * 获取分类列表（管理）
 *
 * @ignore
 */
@PostMapping("/manage/category/list")
public Result<List<Category>> list() {
}

接口详细描述

/**
 * 获取分类列表（管理）
 * 
 * @apiNote 这里是对该接口的详细说明
 */
@PostMapping("/manage/category/list")
public Result<List<Category>> list() {
}

分组方式

官方弃用@tag，使用配置的方式，支持正则

"groups": [
  {
    "name": "管理相关接口",
    "apis": "com.fan.controller.manage.*"
  }
]