【SpringBoot框架篇】23.集成smart-doc插件零侵入自动生成RESTful格式API文档

文章目录

简介
1.配置准备
- 1.1 添加maven插件
- 1.2 创建配置文件
- 1.3 添加统一返回数据格式类
2.接口实战
- 2.1 demo接口类
- 2.2 用户模型类
- 2.3 相关注释描述
- - 2.3.1 接口名称
  - 2.3.2 接口参数
  - - 2.3.2.1 @PathVariable和@RequestParam
    - 2.3.2.2 @RequestBody
    - 2.3.2.3 模型类相关注释
3.文档生成并查看
- 3.1 生成文档命令
- 3.2 查看
4.集成torna统一管理和测试API文档
- 4.1 创建空间并找到3要素(appKey,secret,appToken)
- 4.2 在smart-doc.json中添加三要素
- 4.3 推送文档到torna项目中进行管理
- 4.4 查看项目文档
- - 4.4.1 查看概况视图
  - 4.4.2 查看详细信息
  - 4.4.3 在线测试接口
5.项目配套代码

简介

smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中(swagger则需要写各种注解,严重影响开发效率)。你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

git官网地址: https://gitee.com/smart-doc-team/smart-doc
环境要求: maven 3.3.9+ , jdk 1.8+

1.配置准备 1.1 添加maven插件

在应用的pom文件中添加插件

    
        
            
                com.github.shalousun
                smart-doc-maven-plugin
                2.2.8
                
                    
                    ./src/main/resources/smart-doc.json
                    
                    测试
                    
                    
                        
                        com.alibaba:fastjson
                    
                    
                    
                    
                        
                        com.alibaba:fastjson
                    
                
                
                    
                        
                        compile
                        
                            
                            html

1.2 创建配置文件

在应用的resources目录下创建smart-doc.json配置文件

{
  "outPath": "src\main\resources\static",
  "requestHeaders": [
    {
      "name": "token",
      "type": "string",
      "desc": "身份凭证",
      "value":"",
      "required": false,
      "since": "-"
    }],
  "serverUrl": "http://localhost:8023",
  "projectName": "测试项目RESTful文档",
  "packageFilters": "com.ljm.boot.smartdoc.controller"
}

参数	描述
outPath	配置文档生成目录,本文配的是相对路径,会在应用的resourcesstatic目录下生成
serverUrl	文档中接口访问的地址
requestHeaders	配置默认的请求头参数(一般前后端分类的项目都是通过在header里添加token参数进行身份认证的)
projectName	文档名称
packageFilters	指定需要生成Api文档的包,会递归解析 (如果不配置,默认扫描所有包含@Controller，@RestController的类文件)

1.3 添加统一返回数据格式类

public class JsonResult  implements Serializable {
    
    private int code=200;
    
    private String msg;
    
    private T data;
    
    private String timestamp;
    private static final long serialVersionUID = -7268040542410707954L;
    protected static String successMessage = "操作成功";
    protected static String errorMessage = "操作失败";
    public JsonResult() {}
    public JsonResult(int code) {
        this.setCode(code);
        this.setTimestamp(String.valueOf(System.currentTimeMillis()));
    }
    public JsonResult(int code, String msg) {
        this(code);
        this.setMsg(msg);
    }
    public JsonResult(int code, String msg, T data) {
        this(code, msg);
        this.setData(data);
    }
    public static JsonResult successResult() {
        return new JsonResult(HttpStatus.OK.value(), successMessage);
    }
    public static JsonResult successResult(String msg) {
        return new JsonResult(HttpStatus.OK.value(), defaultSuccessMsg(msg));
    }
    public static  JsonResult successResult(T obj) {
        return new JsonResult(HttpStatus.OK.value(), successMessage, obj);
    }
    public static    JsonResult successResult(String msg, T obj) {
        return new JsonResult(HttpStatus.OK.value(), defaultSuccessMsg(msg), obj);
    }
    public static JsonResult failureResult() {
        return new JsonResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), errorMessage);
    }
    public static JsonResult failureResult(Integer code, String msg) {
        return new JsonResult(code, defautlErrorMsg(msg));
    }
    public static JsonResult failureResult(Integer code, String msg, Object data) {
        return new JsonResult(code, defautlErrorMsg(msg), data);
    }
    public static JsonResult failureResult(String msg) {
        return new JsonResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), defautlErrorMsg(msg));
    }
    public static JsonResult failureResult(Object data) {
        return new JsonResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), errorMessage, data);
    }
    protected static String defautlErrorMsg(String msg) {
        if (StringUtils.hasText(msg)) {
            return msg;
        } else {
            return errorMessage;
        }
    }
    protected static String defaultSuccessMsg(String msg) {
        if (StringUtils.hasText(msg)) {
            return msg;
        } else {
            return successMessage;
        }
    }
}

2.接口实战 2.1 demo接口类

此类写了一套基于RSETful风格的CRUD操作

@RestController
@RequestMapping("/user")
public class UserController {

    
    @GetMapping("/")
    public JsonResult> findAll() {
        User user = new User();
        user.setUsername("test");
        user.setPassword("123456");
        return JsonResult.successResult(Arrays.asList(user));
    }

    
    @GetMapping("/{id}")
    public JsonResult findById(@PathVariable String id) {
        User user = new User();
        user.setUsername("test");
        user.setPassword("123456");
        return JsonResult.successResult(user);
    }


    
    @PostMapping("/")
    public JsonResult save(@RequestParam("username") String username, @RequestParam("password") String password) {
        return JsonResult.successResult();
    }

    
    @PostMapping("/requestBody")
    public JsonResult save(@RequestBody User user) {
        return JsonResult.successResult();
    }

    
    @DeleteMapping("/{id}")
    public JsonResult deleteById(@PathVariable String id) {
        return JsonResult.successResult();
    }
}

2.2 用户模型类

public class User implements Serializable {

    
    @JsonIgnore
    private Integer id;
    
    private String username;

    
    private String password;

    
    private Integer age;
	//省略 get,set 方法...
}

2.3 相关注释描述 2.3.1 接口名称

必须是注释信息里的第一行文字

	
	@RestController
    
    @GetMapping("/")

2.3.2 接口参数 2.3.2.1 @PathVariable和@RequestParam

在接口注释名称下面通过 @param 进行参数和描述映射

    
    @GetMapping("/{id}")
    public JsonResult findById(@PathVariable String id) {}
    
    @PostMapping("/login")
    public JsonResult login(@RequestParam("username") String username, @RequestParam("password") String password) {}

2.3.2.2 @RequestBody

使用@RequestBody时候,则需要到对应的模型类中添加注释描述即可

 
    @PostMapping("/")
    public JsonResult save(@RequestBody User user) {
        return JsonResult.successResult();
    }

2.3.2.3 模型类相关注释

模型类的注释既可以作为接口请求使用,也可以作为接口返回数据使用

    
    @JsonIgnore
    private Integer id;

    
    private String username;

参数	描述
@ignore	接口请求时这个参数忽略掉(文档中不会生成)
@required	接口请求时这个参数是必传的(文档中描述会显示required=true)
@JsonIgnore	接口返回的JSON数据中忽略该参数(文档中不会生成)

其它的注释@tag描述请查看官网: 自定义tag使用

3.文档生成并查看 3.1 生成文档命令

只写了常用的三种,本文使用的是第一种.其它的请参考官网。
第三种是当项目是父子工程的时候用到的,依赖的maven插件也要在父工程的pom.xml中定义,无需在子工程里配置.

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//如果是父子工程的情况下,在父工程目录执行mvn命令并通过pl指定模块名称 smartModelName 
mvn smart-doc:markdown -Dfile.encoding=UTF-8  -pl :smartModelName -am

在应用根目录下命令行中执行mvn -Dfile.encoding=UTF-8 smart-doc:html命令，看到BUILD SUCCESS代表着运行成功,然后去resource/static目录下查看文档.

3.2 查看

双击api.html文件查看,或者访问项目地址 http://localhost:8023/api.html查看.

4.集成torna统一管理和测试API文档

如果不需要使用第三方应用管理API文档或测试的可以跳过此章
项目部署使用地址: https://gitee.com/durcframework/torna#%E4%BD%BF%E7%94%A8%E6%AD%A5%E9%AA%A4

部署完成后访问 http://localhost:7700/ 查看项目
账号: admin@torna.cn 密码: 123456

4.1 创建空间并找到3要素(appKey,secret,appToken)

应用启动后登录然后创建空间

点击刚创建的空间名称跳转到空间里,点击创建项目

点击开放用户创建一个账号信息

创建完会自动生成AppKey和Secret参数

点击项目里面的接口文档菜单,然后点击模块列表的添加按钮添加一个模块。

点击模块里的OpenAPI按钮，然后获取到Token信息

到此,三要素已经都有了。

4.2 在smart-doc.json中添加三要素

{
  "appKey": "20211009896416441941622784",
  "secret": "JUwrw.7B%69%xa.nBq$,Vd#CZY&T8sh0",
  "appToken": "c7d746791f2947a8b637b0440c65cf62",
  "openUrl": "http://127.0.0.1:7700/api",
  "debugEnvName":"测试环境",
  "debugEnvUrl":"http://127.0.0.1:8023"
}

参数	描述
前三个	在torna应用中创建项目空间和模块的时候会自动生成
openUrl	添加torna应用部署的服务器IP(推送文档需要使用)
debugEnvUrl	测试接口用的请求地址

4.3 推送文档到torna项目中进行管理

在应用根目录下命令行中执行mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest命令，看到BUILD SUCCESS代表着运行成功,然后在torna中项目文档中刷新即可查看

mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

4.4 查看项目文档 4.4.1 查看概况视图

4.4.2 查看详细信息

点击上图中的预览查看详细信息

4.4.3 在线测试接口

点击4.4.2图片中的调试接口按钮跳转到测试页面进行接口测试

5.项目配套代码

github地址

创作不易,要是觉得我写的对你有点帮助的话,麻烦在github上帮我点下 Star

【SpringBoot框架篇】其它文章如下,后续会继续更新。

1.搭建第一个springboot项目
2.Thymeleaf模板引擎实战
3.优化代码,让代码更简洁高效
4.集成jta-atomikos实现分布式事务
5.分布式锁的实现方式
6.docker部署,并挂载配置文件到宿主机上面
7.项目发布到生产环境
8.搭建自己的spring-boot-starter
9.dubbo入门实战
10.API接口限流实战
11.Spring Data Jpa实战
12.使用druid的monitor工具查看sql执行性能
13.使用springboot admin对springboot应用进行监控
14.mybatis-plus实战
15.使用shiro对web应用进行权限认证
16.security整合jwt实现对前后端分离的项目进行权限认证
17.使用swagger2生成RESTful风格的接口文档
18.使用Netty加websocket实现在线聊天功能
19.使用spring-session加redis来实现session共享
20.自定义@Configuration配置类启用开关
21.对springboot框架编译后的jar文件瘦身
22.集成RocketMQ实现消息发布和订阅
23.集成smart-doc插件零侵入自动生成RESTful格式API文档

【SpringBoot框架篇】23.集成smart-doc插件零侵入自动生成RESTful格式API文档

Java相关栏目本月热门文章