文章目录
系列文章：
springboot-swagger详解
springboot-优美的Knife4j文档-Swagger进化
Spring Cloud Gateway 网关整合 Knife4j
SpringBoot之如何集成SpringDoc最详细文档
一、概念解释
Swagger和Springdoc是两个常用的工具，用于生成和维护API文档，特别是针对基于REST的Web服务。它们有效地提升了API的可读性和可维护性，帮助开发者、产品经理和其他利益相关者更好地理解和使用所提供的API。
谈到API文档，那就绕不开大名鼎鼎的Swagger，但是你是否还听说过：OpenAPI，Springfox，Springdoc？你第一次看到这些脑瓜子是不是嗡嗡的？
1、OpenAPI
OpenApi 就像 JDBC 一样，制定了各种各样的规范，而 Swagger 和 SpringDoc 则类似于各种各样的数据库驱动，是具体的实现
-
定义 ：OpenAPI 是一个开放标准，用于描述 RESTful API 的接口规范。它最初由 Swagger 项目发展而来，后来成为独立的标准（目前由 OpenAPI Initiative 维护）。
-
版本 ：
- OpenAPI 2.0 ：基于 Swagger 2.0 规范。
- OpenAPI 3.0+ ：是更新的版本，引入了许多新特性（如增强的请求体描述、组件复用等）。
-
作用 ：提供一种标准化的方式来描述 API 的结构、路径、参数、响应等内容，便于开发者和工具生成文档、测试接口。
2、Swagger
它是SmartBear这个公司的一个开源项目，里面提供了一系列工具，包括著名的 swagger-ui。
swagger是早于OpenApi的，某一天swagger将自己的API设计贡献给了OpenApi，然后由其标准化了。
- 定义 ：Swagger 是一组围绕 OpenAPI 标准构建的工具集，包括代码生成器、UI 展示工具等。
- 版本 ：
- Swagger 2.x ：基于 OpenAPI 2.0，是最广泛使用的版本之一。
- Swagger 3.x ：基于 OpenAPI 3.0+，支持更复杂的 API 描述功能。
- 工具 ：
- Swagger UI ：为 OpenAPI 文档提供交互式界面，方便开发者测试 API。
- Swagger Codegen ：根据 OpenAPI 文档生成客户端代码或服务器端框架代码。
3、Springfox
是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了，不支持springboot3，所以业界都在不断的转向我们今天要谈论的另一个库Springdoc，新项目就不要用了。
- 定义 ：Springfox 是一个专门为 Spring 框架设计的库，用于自动生成基于 Swagger/OpenAPI 的 API 文档。
- 特点 ：
- 支持 Spring MVC 和 Spring Boot。
- 主要基于 Swagger 2.x 和 OpenAPI 2.0 。
- 通过注解（如 @Api、@ApiOperation 等）来描述 API。
- 局限性 ：
- 对 OpenAPI 3.0 的支持较弱（尽管有实验性支持，但不够完善）。
- 在 Spring Boot 2.6 及更高版本中，由于兼容性问题（如路径匹配策略的变化），Springfox 的使用变得复杂甚至不可行。
4、Springdoc
算是后起之秀，带着继任Springfox的使命而来。其支持OpenApi规范，支持Springboot3，我们的新项目都应该使用这个。
- 定义 ：Springdoc 是一个现代化的开源库，专为 Spring Boot 应用程序设计，用于自动生成基于 OpenAPI 3.0+ 的 API 文档。
- 特点 ：
- 原生支持 OpenAPI 3.0+ ，并提供对 Spring Boot 2.6+ 的良好兼容性。
- 使用标准的 OpenAPI 注解（如 @Operation、@Parameter 等），而不是 Swagger 特有的注解。
- 提供内置的 Swagger UI，方便开发者快速查看和测试 API。
- 优势 ：
- 更轻量、更易配置。
- 更好的性能和兼容性。
- 社区活跃，更新频繁。
SpringDoc 支持：
- OpenAPI 3
- Spring-boot，全版本都支持。
- JSR-303 中提供的一些注解，例如 @NotNull、@Min、@Max 以及 @Size 等。
- Swagger-ui：SpringDoc 提供的接口 JSON 也可以通过 Swagger-ui 展示出来。
- OAuth 2
- …
5. 关系与区别
| 特性 | Springfox | Springdoc | Swagger | OpenAPI |
|---|---|---|---|---|
| 主要用途 | 自动生成 API 文档 | 自动生成 API 文档 | 工具集，用于生成文档和测试 API | API 描述标准 |
| 支持的规范 | Swagger 2.x / OpenAPI 2.0 | OpenAPI 3.0+ | Swagger 2.x / Swagger 3.x | OpenAPI 2.0 / OpenAPI 3.0+ |
| Spring Boot 兼容性 | 较差（尤其是 2.6+ 版本） | 良好 | 不直接相关 | 不直接相关 |
| 注解 | 使用 Swagger 特定注解（如 @Api） | 使用 OpenAPI 标准注解（如 @Operation） | 使用 Swagger 特定注解 | 定义了标准注解 |
| 工具支持 | 提供 Swagger UI | 提供 Swagger UI | 提供 Swagger UI 和 Codegen | 无直接工具支持，需依赖实现（如 Swagger） |
| 社区活跃度 | 逐渐减少 | 高 | 高 | 高 |
二、什么是swagger
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件；
Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。
三、swagger-ui 和 springfox-swagger-ui
- Swagger Spec 是一个规范。
- Swagger Api 是 Swagger Spec 规范 的一个实现，它支持 jax-rs, restlet, jersey 等等。
- Springfox libraries 是 Swagger Spec 规范 的另一个实现，专注于 spring 生态系统。
- Swagger.js and Swagger-ui 是 javascript 的客户端库，能消费该规范。
- springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ，使得 Spring 服务可以提供服务。
总的来说：
Swagger 是一种规范。
springfox-swagger 是基于 Spring 生态系统的该规范的实现。
springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。
四、springboot使用swagger
1：导包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
注：别用3.0.0，反正我用是出问题了
2：编写swagger配置类
package com.wkl.swaggerspringboot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Description:
* Date: 2022/6/21 - 下午 11:54
* author: wangkanglu
* version: V1.0
*/
@Component
@EnableSwagger2 //开启Swagger2的自动配置
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
}
上面的配置就已经可以使用Swagger了。通过访问http://localhost:8080/swagger-ui.html（自己的项目访问路径/swagger-ui.html）来访问接口文档就可以了。
我写了一个hellocontroller
注：如果不能访问，启动时报错：
Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
请在application.properties中加入以下这段信息
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
原因：
在springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错，解决办法是切换会原先的AntPathMatcher。所以springboot2.6.0以后的加上这个就可以了
3：配置API文档信息
通过apiInfo()属性配置文档信息：
package com.wkl.swaggerspringboot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* Description:
* Date: 2022/6/21 - 下午 11:54
* author: wangkanglu
* version: V1.0
*/
@Component
@EnableSwagger2 //开启Swagger2的自动配置
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置swagger-ui的api信息
private ApiInfo apiInfo(){
Contact contact = new Contact("联系人姓名","http://www.baidu.com/联系人连接","邮箱");
return new ApiInfo("Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()); // 扩展
}
}
4：配置swagger扫描的包
通过上述演示，可以看到系统内添加了默认的controller，那么我们如何配置swagger只扫描我们制定的哪些controller呢？
可以构建Docket时通过select()方法配置怎么扫描接口。
package com.wkl.swaggerspringboot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* Description:
* Date: 2022/6/21 - 下午 11:54
* author: wangkanglu
* version: V1.0
*/
@Component
@EnableSwagger2 //开启Swagger2的自动配置
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller")).build();
}
//配置swagger-ui的api信息
private ApiInfo apiInfo(){
Contact contact = new Contact("联系人姓名","http://www.baidu.com/联系人连接","邮箱");
return new ApiInfo("Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()); // 扩展
}
}
除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
withMethodAnnotation(final Class<? extends Annotation> annotation)// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withClassAnnotation(final Class<? extends Annotation> annotation) // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
basePackage(final String basePackage) // 根据包路径扫描接口
5：配置接口扫描过滤
上述方式可以通过具体的类、方法等扫描接口，还可以配置如何通过请求路径配置：
例如，我有两个controller，一个是hello/,一个是user/,如下：
配置扫描过滤
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
// 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
.paths(PathSelectors.ant("/user/**"))
.build();
}
结果如下；
这里的可选值还有：
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制，返回true扫描，false不扫描
ant(final String antPattern) // 通过ant()表达式控制，返回true扫描，false不扫描
6：配置是否启动Swagger
我们可以通过yml的配置文件，在测试环境中才开启swagger，在正式环境中关闭swagger
@Bean
public Docket docket(Environment environment){
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.enable(b)
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
// 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
.paths(PathSelectors.ant("/user/**"))
.build();
}
正式环境就会提示这个
7：配置API分组
如果没有配置分组，默认是default。通过groupName()方法即可配置分组：
@Bean
public Docket docket(Environment environment){
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.enable(b)
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
// 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
.paths(PathSelectors.ant("/user/**"))
.build()
.groupName("test");
}
那么如何配置多个分组呢？只需要配置多个docket即可；
@Bean
public Docket docketHello(Environment environment){
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.enable(b)
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
// 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
.paths(PathSelectors.ant("/hello/**"))
.build()
.groupName("hello");
}
@Bean
public Docket docketUser(Environment environment){
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.enable(b)
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
// 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
.paths(PathSelectors.ant("/user/**"))
.build()
.groupName("user");
}
8：也可将上述配置放入配置文件中
swagger:
title: 系统模块接口文档
license: Powered By ruoyi
licenseUrl: https://ruoyi.vip
五、Controller提示信息配置
从上述配置中我们可以看到，虽然实现了我们swagger的功能，但是提示却非常不友好，设置到user-controller是干嘛的呢？对此我们可以通过@Api来进行友好提示
1：@API提示整个controller的信息
package com.wkl.swaggerspringboot.controller;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
/**
* Description:
* Date: 2022/6/21 - 下午 11:57
* author: wangkanglu
* version: V1.0
*/
@RestController
@RequestMapping("/user")
@Api(value = "人员user相关操作value",tags = "人员user相关操作tags")
public class UserController {
@PostMapping("test1")
public String test1(@RequestParam String str){
return "usertest1";
}
}
2：@ApiOperation配置在具体方法上
package com.wkl.swaggerspringboot.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
/**
* Description:
* Date: 2022/6/21 - 下午 11:57
* author: wangkanglu
* version: V1.0
*/
@RestController
@RequestMapping("/user")
@Api(value = "人员user相关操作value",tags = "人员user相关操作tags")
public class UserController {
@PostMapping("test1")
@ApiOperation("写的一个user的测试方法")
public String test1(@RequestParam String str){
return "usertest1";
}
}
六、对使用中的实体类进行提示
实体类配置；
@Data
@ApiModel(value = "人员信息", description = "人员信息对象")
public class User {
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
}
controller中用实体类作为参数
@PostMapping("test2")
@ApiOperation("参数为user实体类的测试方法")
public String test2(@RequestBody User user){
return "usertest2";
}
就可以在使用时除了会传入默认值外，还会有实体属性的友好提示
七、swagger的详细注解-详细
1. 核心注解
@Api
- 作用：用于标记一个类是 API 的入口点。
- 常用属性：
tags：为 API 分组。description：API 的描述信息。
- 示例：
@Api(tags = "用户管理", description = "用户相关的操作") @RestController @RequestMapping("/users") public class UserController { // ... }
2. 方法级别注解
@ApiOperation
- 作用：描述一个 API 方法的功能。
- 常用属性：
value：方法的简短描述。notes：方法的详细描述。response：指定返回值类型。httpMethod：指定 HTTP 方法（如 GET、POST 等）。
- 示例：
@ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息") @GetMapping public List<User> getUsers() { // ... }
@ApiResponses 和 @ApiResponse
- 作用：描述一个 API 方法可能的响应结果。
- 常用属性：
code：HTTP 状态码。message：响应的描述信息。response：响应的数据类型。
- 示例：
@ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户") @ApiResponses({ @ApiResponse(code = 200, message = "成功创建用户"), @ApiResponse(code = 400, message = "请求参数错误"), @ApiResponse(code = 500, message = "服务器内部错误") }) @PostMapping public ResponseEntity<User> createUser(@RequestBody User user) { // ... }
3. 参数相关注解
@ApiParam
- 作用：描述方法参数的含义。
- 常用属性：
name：参数名称。value：参数的描述信息。required：是否必填。example：参数的示例值。
- 示例：
@ApiOperation(value = "根据 ID 获取用户") @GetMapping("/{id}") public User getUserById( @ApiParam(name = "id", value = "用户 ID", required = true, example = "1") @PathVariable Long id) { // ... }
@ApiImplicitParams 和 @ApiImplicitParam
- 作用：描述非显式声明的参数（如查询参数、表单参数等）。
- 常用属性：
name：参数名称。value：参数的描述信息。paramType：参数类型（如path、query、header等）。dataType：参数的数据类型。
- 示例：
@ApiOperation(value = "搜索用户") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "string"), @ApiImplicitParam(name = "age", value = "用户年龄", paramType = "query", dataType = "int") }) @GetMapping("/search") public List<User> searchUsers(@RequestParam String name, @RequestParam Integer age) { // ... }
4. 模型相关注解
@ApiModel
- 作用：描述一个实体类的模型。
- 常用属性：
value：模型的名称。description：模型的描述信息。
- 示例：
@ApiModel(value = "用户模型", description = "用户的基本信息") public class User { private Long id; private String name; private Integer age; // getters and setters }
@ApiModelProperty
- 作用：描述实体类中字段的信息。
- 常用属性：
value：字段的描述信息。example：字段的示例值。required：是否必填。hidden：是否隐藏该字段。
- 示例：
@ApiModel(value = "用户模型", description = "用户的基本信息") public class User { @ApiModelProperty(value = "用户 ID", example = "1", required = true) private Long id; @ApiModelProperty(value = "用户名", example = "John Doe", required = true) private String name; @ApiModelProperty(value = "用户年龄", example = "25") private Integer age; // getters and setters }
5. 其他注解
@ApiIgnore
- 作用：忽略某个类、方法或参数，不将其包含在生成的文档中。
- 示例：
@ApiIgnore @GetMapping("/internal") public String internalEndpoint() { return "This endpoint is ignored by Swagger."; }
@ApiModelProperty
- 作用：类似于
@ApiModelProperty，但更适用于复杂嵌套对象的字段描述。
6. OpenAPI 3.0+ 对应注解
如果你使用的是 Springdoc 或支持 OpenAPI 3.0+ 的工具，可以使用以下标准注解替代 Swagger 特有的注解：
- @Operation 替代
@ApiOperation - @Parameter 替代
@ApiParam - @Schema 替代
@ApiModelProperty - @ApiResponse 替代
@ApiResponse
例如：
@Operation(summary = "获取用户列表", description = "返回所有用户的详细信息")
@GetMapping
public List<User> getUsers() {
// ...
}
八、Swagger 注解整理表
1、swagger2.0注解
| 注解 | 作用 | 常用属性 | 示例代码 |
|---|---|---|---|
| @Api | 标记一个类是 API 的入口点，描述整个控制器的功能。 | tags：API 分组description：API 描述信息 | java @Api(tags = "用户管理", description = "用户相关的操作") @RestController public class UserController { } |
| @ApiOperation | 描述一个方法的功能（如 GET、POST 请求）。 | value：方法简短描述notes：方法详细描述response：返回值类型 | java @ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息") @GetMapping public List<User> getUsers() { } |
| @ApiResponses | 定义方法可能的响应结果集合。 | 无（内部包含多个 @ApiResponse） | java @ApiResponses({ @ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 400, message = "参数错误") }) @PostMapping public ResponseEntity<User> createUser(@RequestBody User user) { } |
| @ApiResponse | 描述单个响应结果。 | code：HTTP 状态码message：响应描述response：响应数据类型 | java @ApiResponse(code = 200, message = "成功创建用户", response = User.class) |
| @ApiParam | 描述方法参数的含义。 | name：参数名称value：参数描述required：是否必填example：示例值 | java @ApiParam(name = "id", value = "用户 ID", required = true, example = "1") @PathVariable Long id |
| @ApiImplicitParams | 描述非显式声明的参数（如查询参数、表单参数等）。 | 无（内部包含多个 @ApiImplicitParam） | java @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "string") }) @GetMapping("/search") public List<User> searchUsers(@RequestParam String name) { } |
| @ApiImplicitParam | 描述单个非显式声明的参数。 | name：参数名称value：参数描述paramType：参数类型（如 path、query、header 等）dataType：数据类型 | java @ApiImplicitParam(name = "id", value = "用户 ID", paramType = "path", dataType = "long") |
| @ApiModel | 描述实体类的模型信息。 | value：模型名称description：模型描述 | java @ApiModel(value = "用户模型", description = "用户的基本信息") public class User { } |
| @ApiModelProperty | 描述实体类中字段的信息。 | value：字段描述example：字段示例值required：是否必填hidden：是否隐藏该字段 | java @ApiModelProperty(value = "用户名", example = "John Doe", required = true) private String name; |
| @ApiIgnore | 忽略某个类、方法或参数，不将其包含在生成的文档中。 | 无 | java @ApiIgnore @GetMapping("/internal") public String internalEndpoint() { return "Ignored"; } |
2、OpenAPI 3.0+ 对应注解
如果你使用的是 OpenAPI 3.0+（如 Springdoc），可以使用以下标准注解替代 Swagger 特有的注解：
| Swagger 注解 | OpenAPI 3.0+ 替代注解 | 说明 |
|---|---|---|
| @ApiOperation | @Operation | 描述方法功能，支持更丰富的元信息。 |
| @ApiParam | @Parameter | 描述方法参数，支持更多参数类型（如 in 属性指定参数位置）。 |
| @ApiModel | @Schema | 描述实体类模型，支持嵌套对象和复杂类型定义。 |
| @ApiModelProperty | @Schema | 描述实体类字段，支持更细粒度的约束（如 maxLength、minLength 等）。 |
| @ApiResponse | @ApiResponse | 描述响应结果，支持更复杂的响应结构（如 content 属性定义响应体格式）。 |
3、总结
- Swagger 注解：适用于 Swagger 2.x 和 OpenAPI 2.0，广泛用于 Springfox。
- OpenAPI 注解：适用于 OpenAPI 3.0+，推荐用于 Springdoc 或其他现代化工具。
- 根据项目需求选择合适的注解集，能够帮助你生成清晰、易读的 API 文档。
扫一扫
484
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
