Spring Boot 2.4 集成 OpenApi/Swagger 3.0

​
​

1 摘要

Swagger 作为最受欢迎的后台接口文档生成框架，其知名度自然不用多言。目前市面上绝大多数的 Swagger 还停留在 2.0 时代，而 Swagger 2.0 在 2017 年官方已经停止维护。相对于 2.0 ,Swagger 3.0 依赖更加简洁，更易于集成。本文将介绍基于 Spring boot 2.4 集成 OpenApi Swagger 3.0。

Swagger 官方文档: https://swagger.io/

作者早前文档:

SpringBoot 2.X集成Swagger2生成 RESTFul 风格API接口文档

​

2 核心 Maven 依赖

./demo-swagger3/pom.xml

        <!-- Swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${springfox-swagger3.version}</version>
        </dependency>

这里 ${springfox-swagger3.version} 的版本号为 3.0.0

​

3 核心代码

3.1 application.yml 配置

./demo-swagger3/src/main/resources/application.yml

## Swagger3
swagger3:
  enable: true
  title: Swagger3 demo
  description: Swagger3 demo api document
  authHeaderKey: token

这些信息是自定义的，用于将 Swagger 的信息可配置化

swagger3.enable: 是否启用 Swagger

swagger3.title: 用于定义 Swagger UI 的标题

swagger3.description: 定义Swagger UI 的描述信息

swagger3.authHeaderKey: 定义 Swagger UI 上边的权限认证的头部信息的 key，如使用 token 作为权限认证方式，其 header 的 key 为 token，则 swagger3.authHeaderKey=token

3.2 Swagger 3 配置信息

./demo-swagger3/src/main/java/com/ljq/demo/springboot/swagger3/common/config/Swagger3Config.java

package com.ljq.demo.springboot.swagger3.common.config;

import io.swagger.annotations.Api;
import io.swagger.models.auth.In;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Collections;
import java.util.List;

/**
 * @Description: Swagger3 拦截器
 * @Author: junqiang.lu
 * @Date: 2021/1/25
 */
@EnableOpenApi
@Configuration
public class Swagger3Config {

    @Value("${swagger3.enable}")
    private Boolean enableSwagger;
    @Value("${swagger3.title}")
    private String title;
    @Value("${swagger3.description}")
    private String description;
    @Value("${swagger3.authHeaderKey}")
    private String authHeaderKey;


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
                // 是否启用
                .enable(enableSwagger)
                // Swagger UI 头部信息
                .apiInfo(apiInfo())
                // 指定生成文档的接口
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                // 设置安全认证信息
                .securitySchemes(securitySchemes())
                // 设置安全认证应用范围
                .securityContexts(securityContexts());
    }

    /**
     * Swagger UI 头部信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .build();
    }

    /**
     * 权限认证信息(token)
     *
     * @return
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey(authHeaderKey, authHeaderKey, In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 设置权限认证应用范围
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference(authHeaderKey,
                                new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }

}

使用说明:

@EnableOpenApi Swagger 3.0 的启用注解，如果完全按照 Swagger 的默认配置，则将该注解用在 SpringBoot 启动类上即可

springfox.documentation.spring.web.plugins.Docket 为 Swagger 属性设置类，作者在示例中列出了一些常用的功能属性

enable 属性用于定义是否启用 Swagger。实际项目用途: Swagger 作为接口文档工具，包含了内部接口的众多商业隐私信息，如果暴露在外边会对企业造成不良影响，因此可以通过配置的方式实现开发环境启用 Swagger，而在生产环境中关闭。

springfox.documentation.service.ApiInfo 用于设置 Swagger UI 的头部信息，既生成的 Swagger 接口文档页面的头部。实际项目用途: 写清楚头部信息，能够让前端开发者、测试人员更清晰该文档是属于哪一个项目的，用来做什么的。

springfox.documentation.builders.PathSelectors 用于指定哪些接口生成文档到界面。实际项目中这个功能的作用在于通常一个项目可能有非常多的接口，而后来者往往是在前人的基础上进行，使用一定的过滤条件可以快速定位到自己当前开发的接口，从而更快速地调试。同时该功能还有一个用处，Swagger 的接口文档支持导出功能，如果只想导出某一部分的接口文档，则也可以通过正则表达是来筛选出目标接口。

springfox.documentation.service.SecurityScheme : 用于定义Swagger UI 界面的权限认证。

springfox.documentation.spi.service.contexts.SecurityContext 用于定义权限认证应用范围。 SecurityScheme 必须要与 SecurityContext 搭配使用，才能够实现在界面上输入 token 传递到后台的功能。实际项目用途：现如今，前后端分离的条件下，权限认证通常使用 Auth2.0 框架，即使用 Token 作为权限认证工具，通过设置 token ，则能够实现在 Swagger UI 界面上调试包含 token 的接口，从而避免了因为没有 Token 而无法在 Swagger 界面进行接口调试的尴尬情况。

3.3 Swagger 常用注解使用

3.3.1 请求与返回参数

./demo-swagger3/src/main/java/com/ljq/demo/springboot/swagger3/model/param/AdminUserSaveParam.java

package com.ljq.demo.springboot.swagger3.model.param;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.*;
import java.io.Serializable;

/**
 * 管理员用户新增(单条)
 *
 * @author junqiang.lu
 * @date 2021-01-25 19:23:35
 */
@Data
@ApiModel(value = "管理员用户新增(单条)", description = "管理员用户新增(单条)")
public class AdminUserSaveParam implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 名称
     * */
    @NotBlank(message = "名称 不能为空")
    @ApiModelProperty(value = "名称", name = "name", required = true)
    private String name;
    /**
     * 邮箱,账号
     * */
    @NotBlank(message = "邮箱,账号 不能为空")
    @Email(message = "邮箱格式错误")
    @ApiModelProperty(value = "邮箱,账号", name = "email", required = true)
    private String email;
    /**
     * 登录密码
     * */
    @NotBlank(message = "登录密码 不能为空")
    @ApiModelProperty(value = "登录密码", name = "passcode", required = true)
    private String passcode;
    /**
     * 是否启用,0-未启用,1-启用
     * */
    @NotNull(message = "请设置是否启用")
    @Min(value = 0, message = "是否启用设置错误")
    @Max(value = 1, message = "是否启用设置错误")
    @ApiModelProperty(value = "是否启用,0-未启用,1-启用 不能为空", name = "enabled", required = true, example = "0")
    private Integer enabled;
    /**
     * 等级
     * */
    @NotNull(message = "等级 不能为空")
    @Min(value = 1, message = "等级 至少为 1")
    @ApiModelProperty(value = "等级 不能为空,至少为 1", name = "level", required = true, example = "0")
    private Integer level;

}

@ApiModel 应用java bean 的类上

@ApiModelProperty 应用到字段上

3.3.2 Controller 层

./demo-swagger3/src/main/java/com/ljq/demo/springboot/swagger3/controller/AdminUserController.java

package com.ljq.demo.springboot.swagger3.controller;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.ljq.demo.springboot.swagger3.common.api.ApiResult;
import com.ljq.demo.springboot.swagger3.model.entity.AdminUserEntity;
import com.ljq.demo.springboot.swagger3.model.param.*;
import com.ljq.demo.springboot.swagger3.service.AdminUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

/**
 * 管理员用户
 * 
 * @author junqiang.lu
 * @date 2021-01-25 19:40:57
 */
@Slf4j
@RestController
@RequestMapping(value = "/api/springboot/admin/user")
@Api(value = "管理员用户", tags = "管理员用户")
public class AdminUserController {

	@Autowired
	private AdminUserService adminUserService;

    /**
     * 新增(单条)
     *
     * @param saveParam
     * @return
     */
    @PostMapping(value = "/add", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户新增(单条)",  notes = "管理员用户新增(单条)")
    public ResponseEntity<ApiResult<AdminUserEntity>> save(@Validated @RequestBody AdminUserSaveParam saveParam) {
        return ResponseEntity.ok(ApiResult.success(adminUserService.save(saveParam)));
    }

    /**
     * 查询详情(单条)
     *
     * @param infoParam
     * @return
     */
    @GetMapping(value = "/info", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户查询详情(单条)",  notes = "管理员用户查询详情(单条)")
    public ResponseEntity<ApiResult<AdminUserEntity>> info(@Validated AdminUserInfoParam infoParam) {
        return ResponseEntity.ok(ApiResult.success(adminUserService.info(infoParam)));
    }

    /**
     * 查询列表
     *
     * @param listParam
     * @return
     */
    @GetMapping(value = "/page", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户查询列表",  notes = "管理员用户查询列表")
    public ResponseEntity<ApiResult<IPage<AdminUserEntity>>> page(@Validated AdminUserListParam listParam) {
        return ResponseEntity.ok(ApiResult.success(adminUserService.page(listParam)));
    }

    /**
     * 修改(单条)
     *
     * @param
     * @return
     */
    @PutMapping(value = "/update", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户修改(单条)",  notes = "管理员用户修改(单条)")
    public ResponseEntity<ApiResult<Void>> update(@Validated @RequestBody AdminUserUpdateParam updateParam) {
        adminUserService.update(updateParam);
        return ResponseEntity.ok(ApiResult.success());
    }

    /**
     * 删除(单条)
     *
     * @param deleteParam
     * @return
     */
    @DeleteMapping(value = "/delete", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户删除(单条)",  notes = "管理员用户删除(单条)")
    public ResponseEntity<ApiResult<Void>> delete(@Validated @RequestBody AdminUserDeleteParam deleteParam) {
        adminUserService.delete(deleteParam);
        return ResponseEntity.ok(ApiResult.success());
    }

    /**
     * 批量删除
     *
     * @param deleteBatchParam
     * @return
     */
    @DeleteMapping(value = "/delete/batch", produces = {MediaType.APPLICATION_JSON_VALUE})
    @ApiOperation(value = "管理员用户批量删除",  notes = "管理员用户批量删除")
    public ResponseEntity<ApiResult<Void>> deleteBatch(@Validated @RequestBody AdminUserDeleteBatchParam deleteBatchParam) {
        adminUserService.deleteBatch(deleteBatchParam);
        return ResponseEntity.ok(ApiResult.success());
    }




}

@Api 应用到类上

@ApiOperation 应用到方法上

​

4 Swagger 3.0 界面地址

Swagger 2.0 页面地址

http://ip:port/swagger-ui.html

eg:  
http://127.0.0.1:8080/swagger-ui.html

Swagger 3.0 页面地址

http://ip:port/swagger-ui/

eg:  
http://127.0.0.1:8680/swagger-ui/

​

5 Swagger UI 界面说明

6 推荐参考文档

重磅：Swagger3.0 官方 starter 诞生了，其它的都可以扔了~

SpringBoot 2.X集成Swagger2生成 RESTFul 风格API接口文档

​

7 Github 源码

Gtihub 源码地址 : https://github.com/Flying9001/springBootDemo

个人公众号:404Code,分享半个互联网人的技术与思考，感兴趣的可以关注.