Spring Boot 2.4 集成 OpenApi/Swagger 3.0

分手后的思念是犯贱 2022-10-27 01:36 523阅读 0赞

### 文章目录 ###

*   *   *  1 摘要
         *  2 核心 Maven 依赖
         *  3 核心代码
         *   *  3.1 application.yml 配置
             *  3.2 Swagger 3 配置信息
             *  3.3 Swagger 常用注解使用
             *   *  3.3.1 请求与返回参数
                 *  3.3.2 Controller 层
         *  4 Swagger 3.0 界面地址
         *  5 Swagger UI 界面说明
         *  6 推荐参考文档
         *  7 Github 源码

### 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/][https_swagger.io]

作者早前文档:

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

### 2 核心 Maven 依赖 ###

./demo-swagger3/pom.xml

<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 界面说明 ###

![image-20210202201836814][]

### 6 推荐参考文档 ###

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

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

### 7 Github 源码 ###

**Gtihub 源码地址** : [https://github.com/Flying9001/springBootDemo][https_github.com_Flying9001_springBootDemo]

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

[https_swagger.io]: https://swagger.io/
[SpringBoot 2.X_Swagger2_ RESTFul _API]: https://blog.csdn.net/mrqiang9001/article/details/88929446
[image-20210202201836814]: /images/20221024/8233c37f5d2548f0ad6253650e099856.png
[Swagger3.0 _ starter]: https://mp.weixin.qq.com/s/mbcb-z8L-qkngV0xx_WdQA
[https_github.com_Flying9001_springBootDemo]: https://github.com/Flying9001/springBootDemo
[404Code]: /images/20221024/1a6b921c92524edb9581e12690b92031.png