前言

一个好的可持续交付的项目，项目说明，和接口文档是必不可少的，swagger api 就可以帮我们很容易自动生成api 文档，不需要单独额外的去写，无侵入式，方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目，剩余的时间就可以去约妹子啦

整合swagger api

这里我们自己去整合swagger api比较麻烦，要导入好几个包，有大神帮我们写好了轮子kinfe4j直接对应SpringBoot的启动项，而且在不影响原来使用功能上界面ui做了美化功能做了增强我们直接整合这个就好了

1        <!--api 文档-->
2        <dependency>
3            <groupId>com.github.xiaoymin</groupId>
4            <artifactId>knife4j-spring-boot-starter</artifactId>
5            <version>3.0.1</version>
6        </dependency>

正如官网所说

kinfe4j官方文档点击这里

自定义配置信息

为我们为swagger配置更多的接口说明

1package cn.soboys.core.config;
2
3import cn.hutool.core.collection.CollUtil;
4import cn.soboys.core.ret.ResultCode;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7import org.springframework.http.HttpMethod;
8import springfox.documentation.builders.ApiInfoBuilder;
9import springfox.documentation.builders.PathSelectors;
10import springfox.documentation.builders.RequestHandlerSelectors;
11import springfox.documentation.builders.ResponseBuilder;
12import springfox.documentation.service.ApiInfo;
13import springfox.documentation.service.Contact;
14import springfox.documentation.service.Response;
15import springfox.documentation.spi.DocumentationType;
16import springfox.documentation.spring.web.plugins.Docket;
17
18import javax.annotation.Resource;
19import java.util.Arrays;
20import java.util.List;
21
22/**
23 * @author kenx
24 * @version 1.0
25 * @date 2021/6/21 16:02
26 * api 配置类
27 */
28@Configuration
29public class SwaggerConfigure {
30    @Resource
31    private SwaggerProperty swaggerProperty;
32
33    /**
34     * 构造api 文档
35     * @return
36     */
37    @Bean
38    public Docket createRestApi() {
39        return new Docket(DocumentationType.OAS_30).globalResponses(HttpMethod.POST, this.responseList()) //全局respons信息
40                .apiInfo(apiInfo(swaggerProperty))  //文档信息
41                .select()
42                //文档扫描
43                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //有ApiOperation注解的controller都加入api文档
44                .apis(RequestHandlerSelectors.basePackage(swaggerProperty.getBasePackage())) //包模式
45                .paths(PathSelectors.any())
46                .build();
47    }
48
49    private ApiInfo apiInfo(SwaggerProperty swagger) {
50        return new ApiInfoBuilder()
51                //标题
52                .title(swagger.getTitle())
53                //描述
54                .description(swagger.getDescription())
55                //创建联系人信息 （作者，邮箱，网站）
56                .contact(new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()))
57                //版本
58                .version(swagger.getVersion())
59                //认证
60                .license(swagger.getLicense())
61                //认证协议
62                .licenseUrl(swagger.getLicenseUrl())
63                .build();
64    }
65
66    /**
67     * 全局response 返回信息
68     * @return
69     */
70    private List<Response> responseList() {
71        List<Response> responseList = CollUtil.newArrayList();
72        Arrays.stream(ResultCode.values()).forEach(errorEnum -> {
73            responseList.add(
74                    new ResponseBuilder().code(errorEnum.getCode().toString()).description(errorEnum.getMessage()).build()
75            );
76        });
77        return responseList;
78    }
79}
80

抽出api文档配置模版信息为属性文件方便复用

1
2package cn.soboys.core.config;
3
4import lombok.Data;
5import org.springframework.beans.factory.annotation.Value;
6import org.springframework.boot.SpringBootConfiguration;
7
8/**
9 * @author kenx
10 * @version 1.0
11 * @date 2021/6/21 16:01
12 * api 文档信息
13 */
14@Data
15@SpringBootConfiguration
16public class SwaggerProperty {
17    /**
18     * 需要生成api文档的 类
19     */
20    @Value("${swagger.basePackage}")
21    private String basePackage;
22    /**
23     * api文档 标题
24     */
25    @Value("${swagger.title}")
26    private String title;
27    /**
28     * api文档 描述
29     */
30    @Value("${swagger.description}")
31    private String description;
32    /**
33     * api文档 版本
34     */
35    @Value("${swagger.version}")
36    private String version;
37    /**
38     * api  文档作者
39     */
40    @Value("${swagger.author}")
41    private String author;
42    /**
43     * api 文档作者网站
44     */
45    @Value("${swagger.url}")
46    private String url;
47    /**
48     * api文档作者邮箱
49     */
50    @Value("${swagger.email}")
51    private String email;
52    /**
53     * api 文档 认证协议
54     */
55    @Value("${swagger.license}")
56    private String license;
57    /**
58     * api 文档 认证 地址
59     */
60    @Value("${swagger.licenseUrl}")
61    private String licenseUrl;
62}

简单使用

在你的Controller上添加swagger注解

1@Slf4j
2@Api(tags = "登录")
3public class LoginController {
4    private final IUsersService userService;
5
6    @PostMapping("/login")
7    @ApiOperation("用户登录")
8    public String login(@RequestBody UserLoginParams userLoginParams) {
9        Users u = userService.login(userLoginParams);
10        return "ok";
11    }
12}

注意如启用了访问权限，还需将swagger相关uri允许匿名访问

1/swagger**/**
2/webjars/**
3/v3/**
4/doc.html

重启服务，自带api文档访问链接为/doc.html界面如下:

相比较原来界面UI更加漂亮了，信息更完善功能更强大

Swagger常用注解

Api标记

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

ApiOperation标记

用于请求的方法上表示一个http请求的操作

参数:

value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

ApiParam标记

用于请求方法上对请求参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

参数：

name–参数名
value–参数说明
required–是否必填

ApiModel标记

用于java实体类上表示对类进行说明，用于参数用实体类接收

参数：

value–表示对象名
description–描述都可省略

ApiModelProperty标记

用于方法，字段；表示对model属性的说明或者数据操作更改

参数：

value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

1@ApiModel(value="user对象",description="用户对象user")
2public class User implements Serializable{
3    private static final long serialVersionUID = 1L;
4     @ApiModelProperty(value="用户名",name="username",example="xingguo")
5     private String username;
6     @ApiModelProperty(value="状态",name="state",required=true)
7      private Integer state;
8      private String password;
9      private String nickName;
10      private Integer isDeleted;
11 
12      @ApiModelProperty(value="id数组",hidden=true)
13      private String[] ids;
14      private List<String> idList;
15     //省略get/set
16}

ApiIgnore标记

用于请求类或者方法上，可以不被swagger显示在页面上

ApiImplicitParam标记

用于方法表示单独的请求参数

ApiImplicitParams标记

用于方法，包含多个 @ApiImplicitParam

参数：

name–参数名
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

1  @ApiOperation("查询测试")
2  @GetMapping("select")
3  //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
4  @ApiImplicitParams({
5  @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
6  @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
7  public void select(){
8 
9  }

总结

可以给实体类和接口添加注释信息
接口文档实时更新
在线测试
kinfe4j 在swagger API只做增强，不会改变原有任何使用，更多增加使用功能点击这里进入kinfe4j官网文档

SpringBoot 优雅整合Swagger Api 自动生成文档

前言