前后端接口联调须要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！