目录
- POM
- yml
- [配置自定义的 OpenAPI 规范](#配置自定义的 OpenAPI 规范)
- [拦截器去除 swagger 的接口验证](#拦截器去除 swagger 的接口验证)
- 模型
- [Controller 配置](#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
xml
<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 内网环境中配置,开放外试的话,最好加上授权
yaml
# 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
java
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();
}
}
也可以在配置中分组
java
# 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
java
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);
}
}
模型
java
/**
* 菜单权限表 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 配置
java
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 | 描述复合参数对象,通常用于请求体中的复杂结构。 |