乐趣区

关于java:还在用Swagger试试这款零注解侵入的API文档生成工具跟Postman绝配

前后端接口联调须要 API 文档,咱们常常会应用工具来生成。之前常常应用 Swagger 来生成,最近发现一款好用的 API 文档生成工具smart-doc, 它有着很多 Swagger 不具备的特点,举荐给大家。

SpringBoot 实战电商我的项目 mall(50k+star)地址:https://github.com/macrozheng/mall

聊聊 Swagger

在咱们应用 Swagger 的时候,常常会须要用到它的注解,比方 @Api@ApiOperation 这些,Swagger 通过它们来生成 API 文档。比方上面的代码:

Swagger 对代码的入侵性比拟强,有时候代码正文和注解中的内容有点反复了。有没有什么工具能实现零注解入侵,间接依据代码正文生成 API 文档呢?smart-doc恰好是这种工具!

smart-doc 简介

smart-doc是一款 API 文档生成工具,无需多余操作,只有你标准地写好代码正文,就能生成 API 文档。同时能间接生成 Postman 调试文件,一键导入 Postman 即可调试,十分好用!

smart-doc具备如下长处:

生成 API 文档

接下来咱们把 smart-doc 集成到 SpringBoot 我的项目中,体验一下它的 API 文档生成性能。

  • 首先咱们须要在我的项目中增加 smart-doc 的 Maven 插件,能够发现 smart-doc 就是个插件,连依赖都不必增加,真正零入侵啊;
<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>mall-tiny-smart-doc</projectName>
    </configuration>
</plugin>
  • 接下来在我的项目的 resources 目录下,增加配置文件smart-doc.json,属性阐明间接参考正文即可;
{
  "serverUrl": "http://localhost:8088", // 指定后端服务拜访地址
  "outPath": "src/main/resources/static/doc", // 指定文档的输入门路,生成到我的项目动态文件目录下,随我的项目启动能够查看
  "isStrict": false, // 是否开启严格模式
  "allInOne": true, // 是否将文档合并到一个文件中
  "createDebugPage": false, // 是否创立能够测试的 html 页面
  "packageFilters": "com.macro.mall.tiny.controller.*", //controller 包过滤
  "style":"xt256", // 基于 highlight.js 的代码高设置
  "projectName": "mall-tiny-smart-doc", // 配置本人的项目名称
  "showAuthor":false, // 是否显示接口作者名称
  "allInOneDocFileName":"index.html" // 自定义设置输入文档名称
}
  • 关上 IDEA 的 Maven 面板,双击 smart-doc 插件的 smart-doc:html 按钮,即可生成 API 文档;

  • 此时咱们能够发现,在我的项目的 static/doc 目录下曾经生成如下文件;

  • 运行我的项目,拜访生成的 API 接口文档,发现文档十分具体,包含了申请参数和响应后果的各种阐明,拜访地址:http://localhost:8088/doc/ind…

  • 咱们回过来看下实体类的代码,能够发现咱们只是标准地增加了字段正文,生成文档的时候就主动有了;
public class PmsBrand implements Serializable {
    /**
     * ID
     */
    private Long id;

    /**
     * 名称
     * @required
     */
    private String name;

    /**
     * 首字母
     * @since 1.0
     */
    private String firstLetter;

    /**
     * 排序
     */
    private Integer sort;

    /**
     * 是否为品牌制造商(0,1)
     */
    private Integer factoryStatus;

    /**
     * 显示状态(0,1)
     * @ignore
     */
    private Integer showStatus;

    /**
     * 产品数量
     */
    private Integer productCount;

    /**
     * 产品评论数量
     */
    private Integer productCommentCount;

    /**
     * 品牌 logo
     */
    private String logo;

    /**
     * 专区大图
     */
    private String bigPic;

    /**
     * 品牌故事
     */
    private String brandStory;
    // 省略 getter、setter 办法
}
  • 再来看下 Controller 中代码,咱们同样标准地在办法上增加了正文,生成 API 文档的时候也主动有了;
/**
 * 商品品牌治理
 */
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;
    
    /**
     * 分页查问品牌列表
     *
     * @param pageNum 页码
     * @param pageSize 分页大小
     */
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    @ResponseBody
    @PreAuthorize("hasRole('ADMIN')")
    public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
                                                                Integer pageNum,
                                                        @RequestParam(value = "pageSize", defaultValue = "3")
                                                                Integer pageSize) {List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
        return CommonResult.success(CommonPage.restPage(brandList));
    }
}
  • 当然 smart-doc 还提供了自定义正文 tag,用于加强文档性能;

    • @ignore:生成文档时是否要过滤该属性;
    • @required:用于润饰接口申请参数是否必须;
    • @since:用于润饰接口中属性增加的版本号。
  • 为了写出优雅的 API 文档接口,咱们常常会对返回后果进行对立封装,smart-doc也反对这样的设置,在 smart-doc.json 中增加如下配置即可;
{
  "responseBodyAdvice":{ // 对立返回后果设置
    "className":"com.macro.mall.tiny.common.api.CommonResult" // 对应封装类
  }
}
  • 咱们也常常会用枚举类型来封装状态码,在 smart-doc.json 中增加如下配置即可;
{
  "errorCodeDictionaries": [{ // 错误码列表设置
    "title": "title",
    "enumClassName": "com.macro.mall.tiny.common.api.ResultCode", // 错误码枚举类
    "codeField": "code", // 错误码对应字段
    "descField": "message" // 错误码形容对应字段
  }]
}
  • 配置胜利后,即可在 API 文档中生成 错误码列表

  • 有时候咱们也会想给某些接口增加自定义申请头,比方给一些须要登录的接口增加 Authorization 头,在 smart-doc.json 中增加如下配置即可;
{
  "requestHeaders": [{ // 申请头设置
    "name": "Authorization", // 申请头名称
    "type": "string", // 申请头类型
    "desc": "token 申请头的值", // 申请头形容
    "value":"token 申请头的值", // 申请头的值
    "required": false, // 是否必须
    "since": "-", // 增加版本
    "pathPatterns": "/brand/**", // 哪些门路须要增加申请头
    "excludePathPatterns":"/admin/login" // 哪些门路不须要增加申请头
  }]
}
  • 配置胜利后,在接口文档中即可查看到自定义申请头信息了。

应用 Postman 测试接口

咱们应用 Swagger 生成文档时候,是能够间接在下面测试接口的,而 smart-doc 的接口测试能力真的很弱,这兴许是它拥抱 Postman 的起因吧,毕竟 Postman 是十分好用的接口测试工具,上面咱们来联合 Postman 应用下!

  • smart-doc内置了 Postman 的 json 生成插件,能够一键生成并导入到 Postman 中去,双击 smart-doc:postman 按钮即可生成;

  • 此时将在我的项目的 static/doc 目录下生成 postman.json 文件;

  • postman.json 文件间接导入到 Postman 中即可应用;

  • 导入胜利后,所有接口都将在 Postman 中显示,这下咱们能够欢快地测试接口了!

总结

smart-doc的确是一款好用的 API 文档生成工具,尤其是它零注解侵入的特点。尽管它的接口测试能力有所有余,然而能够一键生成 JSON 文件并导入到 Postman 中去,应用起来也是十分不便的!

参考资料

官网文档:https://gitee.com/smart-doc-t…

我的项目源码地址

https://github.com/macrozheng…

本文 GitHub https://github.com/macrozheng/mall-learning 曾经收录,欢送大家 Star!

退出移动版