SpringBoot 2.3 升级到 SpringBoot 2.7 爬坑– SpringDoc & Swagger (支持 SpringBoot 3.X)

目录

• POM
• yml
• 配置自定义的 OpenAPI 规范
• 拦截器去除 swagger 的接口验证
• 模型
• Controller 配置
• 常用注解

注意：Swagger支持SpringBoot2.0但不支持SpringBoot3.0
OpenApi
OpenApi是一个用于描述、定义和共享 RESTful API 文档的规范。最新规范是 OpenAPI 3.0

Swagger
Swagger 是一个用于设计和测试 RESTful APIs 的工具。
它提供了API 描述、请求和响应示例、API 测试和文档生成等丰富的功能。最新版本是Swagger3,支持OpenAPI3.0规范

SpringFox
SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中。

SpringDoc
SpringDoc 也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中

OpenAPI 定义了一种标准的格式来表示 API 文档，而 Swagger 是一个实现 OpenAPI 规范的工具

SpringFox和SpringDoc是Spring社区维护的一个非官方项目，分别帮助开发者将Swagger 2、Swagger 3集成到Spring中。SpringFox已经很久没有更新，因此SpringDoc无疑是更好的选择。

POM

<springdoc.version>1.6.9</springdoc.version>  <!--这个包，包括了 swagger-annotations 、 webmvc-core等--> <dependency>     <groupId>org.springdoc</groupId>     <artifactId>springdoc-openapi-ui</artifactId>     <version>${springdoc.version}</version> </dependency> <!--swagger在内网开发环境，所以安全方面的暂时没加--> <!-- <dependency>     <groupId>org.springdoc</groupId>     <artifactId>springdoc-openapi-security</artifactId>     <version>${springdoc.version}</version> </dependency> --> 

yml

只要 dev、test 内网环境中配置，开放外试的话，最好加上授权

# Docs API配置 springdoc:   swagger-ui:     # API文档, 默认路径:swagger-ui/index.html, 通过http://localhost:8080/docs/index.html访问     path: /docs/index.html     # 开启Swagger UI界面     enabled: true     # 根据HTTP方法对API路径进行排序     operations-sorter: method   api-docs:     # OpenAPI的路径描述，默认路径:/v3/api-docs, 通过http://localhost:8080/docs/api访问文档描述     # OpenAPI描述定义默认为JSON格式, 通过http://localhost:8080/docs/api.yaml获取yaml格式     path: /docs/api     # 开启api-docs     enabled: true   # 配置需要生成接口文档的扫描包路径   packages-to-scan: com.cuwor.admin.controller   # 配置需要生成接口文档的接口路径   # paths-to-match:  /test/**,/user/** 

配置自定义的 OpenAPI 规范

OpenApiConfig

package com.vipsoft.base.config;  import io.swagger.v3.oas.models.ExternalDocumentation; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.License; import org.springdoc.core.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration;  @Configuration public class OpenApiConfig {     /**      * 配置自定义的 OpenAPI 规范      * 通过 @Bean 注解声明该方法返回一个 Spring Bean，该 Bean 是一个 OpenAPI 对象      * 该方法允许通过 Spring Context 初始化 OpenAPI 对象，并自定义 API 的标题、版本、描述等信息      *      * @return 自定义的 OpenAPI 对象      */     @Bean     public OpenAPI customOpenAPI() {         // 创建并配置 OpenAPI 对象         return new OpenAPI()                 .info(new Info()                         .title("VipSoft API")            // 设置 API 标题                         .version("v2.0.1")             // 设置 API 版本                         .description("后台接口服务")     // 设置 API 描述                         .license(new License().name("Apache 2.0").url("http://www.vipsoft.com")) // 设置 API 的许可证信息，包括许可证名称和 URL                         .contact(new Contact()                                 .name("Jimmy")        // 设置联系人名称                                 .url("http://www.vipsoft.com") // 设置联系人的 URL                                 .email("47262947@qq.com"))) // 设置联系人的电子邮件地址                 .externalDocs(new ExternalDocumentation()                         .description("外部文档的描述") // 设置外部文档的描述                         .url("http://www.vipsoft.com")); // 设置外部文档的 URL     }      /**      * 配置并返回一个GroupedOpenApi实例，用于指定一组API接口      *      * @return GroupedOpenApi实例，配置了组名为"test"，匹配路径为"/test/**"的接口      */     @Bean     public GroupedOpenApi testApi() {         return GroupedOpenApi.builder()                 .group("menu") // 设置组名                 .pathsToMatch("/menu/**") // 设置需要匹配的路径模式                 .build();     } } 

也可以在配置中分组

# Docs API配置 springdoc:   swagger-ui:     path: /docs/index.html     enabled: true   group-configs:     - group: '测试1'       paths-to-match: /test/**     - group: '测试2'       paths-to-match: /test/**  

拦截器去除 swagger 的接口验证

WebConfig

package com.vipsoft.admin.config;  import com.vipsoft.admin.interceptor.AuthInterceptor; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.cors.CorsConfiguration; import org.springframework.web.cors.UrlBasedCorsConfigurationSource; import org.springframework.web.filter.CorsFilter; import org.springframework.web.servlet.config.annotation.InterceptorRegistration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;   @Configuration public class WebConfig implements WebMvcConfigurer {      @Autowired     private AuthInterceptor authorizationInterceptor;      /**      * 添加拦截器      */     @Override     public void addInterceptors(InterceptorRegistry registry) {         //拦截路径可自行配置多个 可用 ，分隔开         InterceptorRegistration registration= registry.addInterceptor(authorizationInterceptor);         registration.addPathPatterns("/**");         registration.excludePathPatterns(                 "/swagger-ui.html",                 "/swagger-resources/**",                 "/docs/**",                 "/error",                 "/webjars/**"         );     }      /**      * 跨域配置      */     @Bean     public CorsFilter corsFilter()     {         CorsConfiguration config = new CorsConfiguration();         config.setAllowCredentials(true);         // 设置访问源地址         config.addAllowedOriginPattern("*");         // 设置访问源请求头         config.addAllowedHeader("*");         // 设置访问源请求方法         config.addAllowedMethod("*");         // 有效期 1800秒         config.setMaxAge(1800L);         // 添加映射路径，拦截一切请求         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();         source.registerCorsConfiguration("/**", config);         // 返回新的CorsFilter         return new CorsFilter(source);     } }  

模型

/**  * 菜单权限表 sys_menu  */ @TableName("sys_menu") @Schema(description = "菜单信息") public class SysMenu extends BaseEntity {     private static final long serialVersionUID = 1L;      /** 菜单ID */     @Schema(description = "菜单ID", example = "")     private Long menuId;      /** 菜单名称 */     @Schema(description = "菜单名称", example = "用户管理")     @TableField("menu_name")     private String menuName; } 

Controller 配置

package com.vipsoft.admin.controller;  import com.baomidou.mybatisplus.core.metadata.IPage; import com.vipsoft.admin.entity.SysMenu; import com.vipsoft.admin.service.ISysMenuService; import com.vipsoft.base.core.ApiResult; import com.vipsoft.base.security.AuthIgnore; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController;  import java.util.List;  /**  * 菜单信息  *  */ @Tag(name = "测试API接口", description = "这是一个关于测试API接口的描述") @RestController @RequestMapping("/menu") public class SysMenuController {     @Autowired     private ISysMenuService menuService;      /**      * 获取菜单列表      */     @Operation(summary = "获取菜单列表", description = "通过 MyBatisPlus 获取",method = "GET")     @ApiResponse(responseCode = "1", description = "成功",content = @Content(mediaType = "application/json", schema = @Schema(implementation = SysMenu.class)))     @ApiResponse(responseCode = "-1", description = "获取失败")     @GetMapping("/selectPage")     @AuthIgnore     public ApiResult selectPage(SysMenu menu) {         IPage menus = menuService.selectPage(menu);         return new ApiResult(menus);     } } 

常用注解

注解	描述
@Tag	为一组 API 操作添加标签，便于在文档中组织和分组。
@Operation	描述一个 API 操作，包括摘要和详细描述。
@Parameter	描述方法参数，包括路径变量、请求体和查询参数。
@Schema	描述数据模型的属性和结构，通常用于模型类或 API 方法的参数和返回值。
@ApiResponse	描述单个 HTTP 响应状态码的详细信息。
@ApiResponses	描述多个 HTTP 响应状态码的详细信息。
@RequestBody	指定请求体的内容类型和结构。
@Content	描述响应内容的类型和格式。
@SecurityRequirement	描述 API 操作所需的安全要求，例如认证和授权。
@Hidden	指定某个 API 操作或模型在文档中隐藏。
@Deprecated	表示某个 API 操作或模型已被弃用。
@ArraySchema	描述数组类型的响应内容，通常用于返回列表。
@ExampleObject	提供示例对象，用于 API 文档中展示请求或响应的示例。
@MediaType	指定请求或响应的媒体类型。
@Link	描述 API 之间的链接关系。
@ParameterObject	描述复合参数对象，通常用于请求体中的复杂结构。