SpringBoot整合Smart-doc（替代swagger的接口文档自动生成工具）

一、前言
我们都知道平时写接口文档会比较麻烦，而且遇到需求频繁变更时，修改起来费时费力，那么有没有办法自动生成接口文档呢。答案是有的。通常我们会使用swagger进行接口文档的生成，但是如果你的公司对项目接入了一些安全方面的扫描，就会发现swagger的注解侵入性较强，会被当成安全隐患，那么有没有什么办法可以即实现接口文档的生成，代码侵入性又不强呢，答案也是有的，那就是Smart-doc。那么下面我们就讲讲Smart的引入和使用。
二、如何引入
1、首先在pom文档中添加smart-doc插件，然后等待maven加载，如果无法加载可以先clean，再install或者reimport一下。

        
            
                com.github.shalousun
                smart-doc-maven-plugin
                2.2.1
                
                    
                    ./src/main/resources/smart-doc.json
                    
                    
                        
                        com.alibaba:fastjson

                    
                
                
                    
                        
                        compile
                        
                            html
                        
                    
                
            
        
    

2、加载成功后再maven的插件页面中会展示出smart-doc。

3、在resource目录下创建smart-doc.json，这是smart-doc的配置文件。

{
  "serverUrl": "http://localhost:8080", //指定后端服务访问地址
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看
  "isStrict": false, //是否开启严格模式
  "allInOne": true, //是否将文档合并到一个文件中
  "createDebugPage": false, //是否创建可以测试的html页面
  "packageFilters": "com.ampthon.controller.*", //controller包过滤
  "style":"xt256", //基于highlight.js的代码高设置
  "projectName": "springboot_test", //配置自己的项目名称
  "showAuthor":false, //是否显示接口作者名称
  "allInOneDocFileName":"index.html" //自定义设置输出文档名称
}

4、随便写几个controller接口，注意要写接口注释（接口功能介绍，参数名称说明…），否则生成的内容会遗漏很多细节，这里节选一部分代码。

 
@Controller
@RequestMapping("/api")
public class UserController {
 
    @GetMapping("/getUserById")
    public User getUserByid(String id) {
        return userService.queryUserById(id);
    }

    
    @PostMapping("/queryUserListById")
    public List queryUserListById(@RequestBody UserRequest request) {

        User user = new User();
        if(StringUtils.isNotEmpty(request.getUsername())){
            user.setUsername(request.getUsername());
        }
        if(StringUtils.isNotEmpty(request.getAge())){
            user.setAge(Integer.valueOf(request.getAge()));
        }
        return userService.queryUserList(user);
    }
    }

4、在maven的smart-doc插件中点击 smart-doc：adoc
如果结果为success，则会在你smart-doc.json中指定的outPath位置生成接口文档的文档。
打开后就是这样的效果，每当你修改接口参数后都可以重新生成一遍，免去了写文档的苦恼。当然，smart-doc随着作者的不断更新迭代也推出了更多功能。比如接口调试，dubbo接口文档生成，service接口文档生成等等。这里为大家提供一个官方的地址供大家探索和学习。
smart-doc项目gitee地址

喜欢的朋友欢迎一键三连。我们一起学习，进步~~