Smart-Doc

Smart-Doc是一款强大的基于Java的API文档生成工具。它通过对接口源代码进行分析来生成全面而准确的文档，完全不需要对代码进行任何注入。这种非侵入式的方法确保了无需添加特殊注解或修改代码即可生成文档，使得集成变得无缝且简单

官方文档

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.*"
  }
]