前后端接口联调需要API文档，我们经常使用工具来生成。之前经常用Swagger来生成，最近发现了一个好用的API文档生成工具smart-doc，它有很多Swagger没有的特性，推荐给大家。SpringBoot实战电商项目商城（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-docMaven插件。你会发现smart-doc是一个插件，你甚至不需要添加依赖。这真的是零入侵；com.github.shalousunsmart-doc-maven-plugin2.2.8./src/main/resources/smart-doc.jsonmall-tiny-smart-doc接下来在项目的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.*",//控制器包过滤"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...我们回过头来看看实体类的代码，可以发现我们在生成文档的时候只是规范的添加了字段注解；publicclassPmsBrandimplementsSerializable{/***ID*/privateLongid;/***name*@required*/privateStringname;/***首字母*@since1.0*/privateStringfirstLetter;/***排序*/private整数排序；/***是否为品牌厂商(0,1)*/privateIntegerfactoryStatus;/***显示状态(0,1)*@ignore*/privateIntegershowStatus;/***产品数量*/privateIntegerproductCount;/***商品评论数量*/privateIntegerproductCommentCount;/***品牌标识*/privateStringlogo;/***区域大图*/privateStringbi图形；/***品牌故事*/privateStringbrandStory;//省略getter和setter方法}我们再看一下Controller中的代码。我们还以标准的方式为方法添加了注解，在生成API文档时自动包含注解；/***商品品牌管理*/@Controller@RequestMapping("/brand")publicclassPmsBrandController{@AutowiredprivatePmsBrandServicebrandService;/***分页查询品牌列表**@parampageNum页码*@parampageSize分页大小*/@RequestMapping(value="/list",method=RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult>listBrand(@RequestParam(value="pageNum",defaultValue="1")IntegerpageNum,@RequestParam(value="pageSize",defaultValue="3")IntegerpageSize){ListbrandList=brandService.listBrand(pageNum,pageSize);返回CommonResult.success(CommonPage.restPage(brandList));}}当然，smart-doc也提供了自定义注释标签来增强文档功能；@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":[{//请求头Set"name":"Authorization",//请求头名称"type":"string",//请求头类型"desc":"token请求头值",//requestheaderdescription"value":"token请求头的值",//请求头的值"required":false,//是否必须"since":"-",//添加版本"pathPatterns":"/brand/**",//哪些路径需要添加请求头"excludePathPatterns":"/admin/login"//哪些路径不需要添加请求头}]}配置成功后，可以在接口文档中查看自定义请求头信息。使用Postman测试接口我们在使用Swagger生成文档的时候，可以直接在上面测试接口，而smart-doc的接口测试能力实在是太弱了。这可能就是它拥抱Postman的原因。毕竟Postman是非常好用的。接口测试工具，和Postman一起使用吧！smart-doc内置了Postmanjson生成插件，可以一键生成导入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...本文的githubhttps://github.com/macrozheng/商城-学习已收录，欢迎Star！
