Springboot项目使用smart-doc+Apifox 便捷生成管理接口文档

Gangbb

已于 2022-01-19 19:47:55 修改

阅读量8.2k

点赞数 9

分类专栏： java实战开发 # SpringBoot 文章标签： spring boot java 后端 Apifox smart-doc

于 2022-01-19 19:47:14 首次发布

本文链接： https://blog.csdn.net/qq_37132495/article/details/122569906

版权

java实战开发同时被 2 个专栏收录

84 篇文章 29 订阅

订阅专栏

SpringBoot

20 篇文章 8 订阅

订阅专栏

1. 前言

相信大家在Java开发中都用过不少接口文档工具，最常见的就是Swagger了。但它有一个不好的缺点就是，想要接口文档清晰和美观需要加入许多声明和注解，代码的侵入性很强。最近在维护一个老的项目，项目中没有用到Swagger，之前前后端的交互用的是Yapi，接口写好了，手动在Yapi上手写一遍文档，真的要吐血，于是决定寻找一款工具可以方便快捷的生成API文档。于是乎百度谷歌各类工具，以下是我尝试过的工具或者平台：

可以说市面上常用的都试过了一遍，最后选定了smart-doc+Apifox的组合！

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

Apifox: https://www.apifox.cn/#

PS：smart-doc 推荐搭配Torna一起使用，我看了Torna确实做得不错，也是开源的，可以私有化部署用起来，一般情况也够用了，但是我想要测试用例保存功能(并且问过Torna作者不打算做这个功能)，所以选择了Apifox。

2. 使用流程

按 smart-doc和JavaDoc的标准写好参数、方法、类等的注释(这一点深得我心，我是一个很喜欢写注释的程序员，非常鄙视一点注释都不写的猿类，代码全裸，维护和看着都贼不舒服，用了这个工具可以让项目最起码的一些注释会有。)
PS：这个注释标准就是很通常的注释标准！
引入 smart-doc的Maven插件，生成openapi.json文件
在Apifox中导入openapi.json文件，生成和管理对应的接口

3. 使用示例

3.1 接口代码编写

Controller增删查改

package com.luqiao.boot.controller.auth;


/**
 * 部门相关接口
 *
 * @author Gangbb
 * @date 2022/1/16
 **/
@RestController
@RequestMapping("/auth/dept")
public class AuthDeptController extends BaseController {

    private final IAuthOrganizationService organizationService;

    public AuthDeptController(IAuthOrganizationService organizationService) {
        this.organizationService = organizationService;
    }

    /**
     * 获取组织下部门列表
     *
     * @param dto 部门列表请求 dto
     * @return ApiResult<PageResult<DeptListVO>> 部门列表请求返回参数
     * @author Gangbb
     * @date 2021/10/29
     **/
    @GetMapping("/list")
    public ApiResult<PageResult<DeptListVO>> list(@Validated DeptListDTO dto) {

        return ApiResult.success(organizationService.getDeptList(dto));
    }

    /**
     * 添加部门
     *
     * @param addDeptDTO 新增部门 dto
     * @return ApiResult 操作结果
     * @author Gangbb
     * @date 2021/10/29
     **/
    @PostMapping
    public ApiResult add(@RequestBody @Validated AddDeptDTO addDeptDTO) {
        // DTO转换
        AddOrganizationDTO addOrganizationDTO = AddDeptDTO.INSTANCE.toAddOrganizationDTO(addDeptDTO);

        return toApiRes(organizationService.insertOrganization(addOrganizationDTO));
    }


    /**
     * 编辑部门
     *
     * @param updateDeptDTO
     * @return ApiResult 操作结果
     * @author Gangbb
     * @date 2021/10/29
     **/
    @PutMapping
    public ApiResult updateDept(@RequestBody @Validated UpdateDeptDTO updateDeptDTO) {
        UpdateOrgDTO updateOrgDTO = UpdateDeptDTO.INSTANCE.toUpdateOrgDTO(updateDeptDTO);

        return toApiRes(organizationService.editOrg(updateOrgDTO));
    }

    /**
     * 删除部门
     *
     * @param ids 待删除部门的id数组
     * @return ApiResult 操作结果
     * @author Gangbb
     * @date 2021/10/26
     **/
    @DeleteMapping("/{ids}")
    public ApiResult deleteDept(@NotEmpty(message = "ids不能为空") @PathVariable Long[] ids) {

        return toApiRes(organizationService.deleteOrg(ids));
    }
}

其中一个DTO(请求参数)和VO(返回参数)代码示例：

/**
 * 部门列表请求 dto
 *
 * @author Gangbb
 * @date 2022/1/19
 **/
@Data
public class DeptListDTO extends PageRequest {

    /** 组织名称 */
    private String deptName;

    /** 组织架构id*/
    @NotNull(message = "所属组织架构(公司)id organizationId 不能为空")
    private Long organizationId;

}

/**
 * 部门列表请求返回参数
 *
 * @author Gangbb
 * @date 2022/1/19
 **/
@Data
public class DeptListVO {
    /**
     * 部门id
     */
    private Long id;

    /**
     * 部门名字
     */
    private String deptName;

    /**
     * 备注
     */
    private String remark;

}

代码中的逻辑内容和未贴出的方法和类不是重点，重点看代码的注释就行！就是最基本的注释。

3.2 引入Smart-doc插件

我这里是单体多模块项目，在根pom.xml引入：

<!--编译及打包项目配置-->
    <build>
        <plugins>
            <!--smart-doc begin-->
            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.3.6</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称，推荐使用动态参数，例如${project.description}-->
                    <!--如果smart-doc.json中和此处都未设置projectName，2.3.4开始，插件自动采用pom中的projectName作为设置-->
                    <projectName>test-system</projectName>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <!--smart-doc end-->
        </plugins>
    </build>

在放着Controller的模块的/src/main/resources路径下编写smart-doc.json文件。

以下是我的示例配置，具体配置详解可以看官网。

{
  "serverUrl": "http://127.0.0.1:8088", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "packageFilters": "com.xxx.boot.controller.auth.AuthDeptController",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则com.test.controller.*
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "style":"atelier-cave-light", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
  "projectName": "test-system",//配置自己的项目名称
  "framework": "spring",//smart-doc默认支持spring和dubbo框架的文档，使用默认框架不用配置，当前支持spring、dubbo、JAX-RS(待完善)
  "skipTransientField": true,//目前未实现
  "sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
  "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
  "requestFieldToUnderline":false,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "responseFieldToUnderline":false,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始
  "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since 1.8.8版本开始
  "allInOneDocFileName":"test-system.html",//自定义设置输出文档名称, @since 1.9.0
  "requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
  "responseExample":"true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0
  "displayActualType":true,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
  "revisionLogs": [{ //文档变更记录，非必须
    "version": "1.0", //文档版本号
    "revisionTime": "2021-01-19 10:30", //文档修订时间
    "status": "update", //变更操作状态，一般为：创建、更新等
    "author": "Gangbb", //文档变更作者
    "remarks": "desc" //变更描述
  }],
  "requestHeaders": [
    { //设置请求头，没有需求可以不设置
      "name": "AUTH-TOKEN",//请求头名称
      "type": "string",//请求头类型
      "desc": "请求token,通过登录接口获取",//请求头描述信息
      "value":"token请求头的值",//不设置默认null
      "required": true
//      "pathPatterns": "/auth/**,/system/**",//
//      "excludePathPatterns":"/common/**"//
    }
  ],
  "responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
    "className":"com.luqiao.cloud.security.luqiaointernal.core.ApiResult" //通用响应体
  }
}

3.3 生成文档

根目录下使用插件

或者使用命令：

//生成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
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi

结果：

它自带生成的文档已经很不错了，也能支持调试，我下面再用Apifox是为了管理所有项目的接口，接口权限等等。

3.4 接口导入Apifox

接口已经导入了：

可以进行管理了。

4. 总结

本文只介绍了smart-doc和Apifox最基本的使用截图，详细体验可以自己用用看，它们官网都介绍得很全面。总体来说这个组合搭配使用还是不错的。不过有一点不好就是Apifox私有化部署应该是要收费，费用怎么样还没有问过。目前Saas版是免费使用的，还有一个工具Apipost跟Apifox做得差不多，没看过，听说也不错。不贵的话，未来收费可以跟公司提，买一个版本。如果不想用了可以支持导出，到时候再导出到其他的工具也行。

最后提一句smart-doc 推荐搭配Torna也是不错的，未来Torna再发展几个版本会考虑使用。