中经常使用 SpringDoc 3.x 详解 Spring Boot 2

大家好，我是码哥，《Redis 高手心法》作者。

SpringBoot 曾经成为 Java 开发的首选框架，当天码哥跟大家聊一聊 Spring Boot3 如何与 Swagger3 集成打造一个牛逼轰轰的接口文档。

咱们都被接口文档折磨过，前端埋怨后端的接口文档一坨屎；后端觉得写接口文档糜费期间。

每个名目都有成千盈百个接口调用，这时刻再要求人工编写接口文档并且保证文档的实时更新简直是一件无法能成功的事，所以这时刻咱们迫切须要一个工具，一个能帮咱们智能化生成接口文档以及智能更新文档的工具。

它就是 Swagger。

Swagger 的外围现实是经过定义和形容 API 的规范、结构和交互方式，以提高 API 的可读性、牢靠性和易用性，同时降落 API 开发的难度和开发者之间的沟通老本。

这里我驳回了 Swagger3.0（Open API 3.0）的方式集成到 SpringBoot。springfox-boot-start 和 springfox-swagger2 都是基于 Swagger2.x 的。

这里将引见 springdoc-openapi-ui，它是 SpringBoot 基于 Open API 3.0（Swagger3.0）

Springfox 是一套可以协助 Java 开发者智能生成 API 文档的工具，它是基于 Swagger 2.x 基础上开发的。

除了集成 Swagger 2.x，Springfox 还提供了一些额外性能，例如自定义 Swagger 文档、API 版本控制、恳求验证等等。

SpringDoc 对应坐标是 springdoc-openapi-ui，它是一个集成 Swagger UI 和 ReDoc 的接口文档生成工具，在经常使用上与 springfox-boot-starter 相似，但提供了更为灵敏、性能愈增弱小的工具。

其中除了可以生成 Swagger UI 格调的接口文档，还提供了 ReDoc 的文档渲染方式，可以智能注入 OpenAPI 规范的 JSON 形容文件，支持 OAuth2、JWT 等认证机制，并且支持全新的 OpenAPI 3.0 规范。

须要留意的是，咱们普通不会选用原生的 Swagger maven 坐标来集成 Swagger。而是经过 springdoc-openapi-ui 的 Maven 坐标。

它可以很好的和 Spring 或 SpringBoot 名目集成；这个坐标也被 Spring 社区宽泛支持和认可，并被以为是集成 Swagger UI 和 OpenAPI 规范的一个低劣选用。

在该示例中，我经常使用 Spring Boot 3.0.2 集成 Swagger 3.0。

springdoc-openapi-starter-webmvc-ui：目前最新版本是 2.6.0，实用于 Spring Boot 3.x 和 Spring Framework 6。支持 Jakarta 命名空间（例如，jakarta.validation），适宜 Spring Boot 3 的 Jakarta EE 转换。

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency></dependencies>

咱们经过性能类的方式创立一个 OpenAPI 的 Bean 对象就可以创立 Swagger3.0 的文档说明。

import io.swagger.v3.oas.models.ExternalDocumentation;import io.swagger.v3.oas.models.OpenAPI;import io.swagger.v3.oas.models.info.Info;import io.swagger.v3.oas.models.info.License;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@Configurationpublic class Swagger3Config {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("码哥跳动 Swagger3 详解").description("Swagger3 Spring Boot 3.0 application").version("v0.0.1").license(new License().name("Apache 2.0").url("http://springdoc.org"))).externalDocs(new ExternalDocumentation().description("swagger 3 详解").url("https://springshop.wiki.github.org/docs"));}}

OpenAPI 对象是 Swagger 中的外围类之一，用于形容整个 API 的结构和元数据。

Swagger2 和 Swagger3 经常使用的是齐全不同的两套注解，所以原本经常使用 Swagger2 相关注解的代码页须要齐全迁徙，改为经常使用 Swagger3 的注解。

经过以下性能来控制 swagger 的开关和访问地址：WEB 界面的显示基于解析 JSON 接口前往的结果, 假设 api-docs 封锁, swagger-ui 即使 enable 也无法经常使用。

server:port: 8013spring:application:name: magebyte-swaggerspringdoc:api-docs:enabled: true # 开启OpenApi接口path: /v3/api-docs# 自定义门路，默以为 "/v3/api-docs"swagger-ui:enabled: true # 开启swagger界面，依赖OpenApi，须要OpenApi同时开启path: /swagger-ui.html # 自定义门路，默以为"/swagger-ui/index.html"# Packages to include,多个用 , 宰割packagesToScan: zero.magebyte.magebyte.swagger.controller

须要留意的是，packagesToScan 用于指定 Controller 接口包门路。

Swagger3 用 @Schema 注解对象和字段, 以及接口中的参数类型。

@Setter@Getter@Schema(description = "照应前往数据对象")public class Result<T> implements Serializable {@Schema(title = "code",description = "照应码",format = "int32",requiredMode = Schema.RequiredMode.REQUIRED)private Integer code;@Schema(title = "msg",description = "照应信息",accessMode = Schema.AccessMode.READ_ONLY,example = "成功或失败",requiredMode = Schema.RequiredMode.REQUIRED)private String message;@Schema(title = "data", description = "照应数据", accessMode = Schema.AccessMode.READ_ONLY)private T>