系列文章：
springboot-swagger详解
springboot-优美的Knife4j文档-Swagger进化
Spring Cloud Gateway 网关整合 Knife4j
SpringBoot之如何集成SpringDoc最详细文档
一般在使用 Spring Boot 开发前后端分离项目的时候，都会用到 Swagger。Swagger 是一个规范和完整的框架，用于生成、描述、调试和可视化 RESTful 风格的 Web API 服务框架。
但随着系统功能的不断增加，接口数量的爆炸式增长，Swagger 的使用体验就会变得越来越差，比如请求参数为 JSON 的时候没办法格式化，返回结果没办法折叠，还有就是没有提供搜索功能。
刚好最近发现 Knife4j 弥补了这些不足，赋予了 Swagger 更强的生命力，于是就来给大家安利一波。
1、关于 Knife4j
Knife4j 的前身是 swagger-bootstrap-ui，是 springfox-swagger-ui 的增强 UI 实现。swagger-bootstrap-ui 采用的是前端 UI 混合后端 Java 代码的打包方式，在微服务的场景下显得非常臃肿，改良后的 Knife4j 更加小巧、轻量，并且功能更加强大
2：由swagger-ui变为Knife4j
如果项目中之前使用过 Swagger 生成接口文档，切换到 Knife4j 可以说是非常的丝滑，只需要两步：
在 pom.xml 文件中把 springfox-boot-starter 替换为 knife4j-spring-boot-starter；
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索3.X最新版本号-->
<version>3.0.2</version>
</dependency>
访问地址由原来的 http:// h o s t : {host}: host:{port}/swagger-ui.html 切换到 http:// h o s t : {host}: host:{port}/doc.html
注：如果想了解swagger-ui可以去参考swagger-springboot详解这个文章
3：配置使用Knife4j
1:导包
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索3.X最新版本号-->
<version>3.0.2</version>
</dependency>
2:配置Knife4j配置类
package com.wkl.swagger_demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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的自动配置
@EnableOpenApi //开启Knife4j配置
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，去配置扫描接口
.select()
// RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.wkl.swagger_demo.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<>()); // 扩展
}
}
3:写controller
package com.wkl.swagger_demo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
/**
* @author wangkanglu
* @version 1.0
* @description
* @date 2022-08-26 10:23
*/
@RestController
@RequestMapping("/hello")
@Api(tags = "利用helloworld测试swagger")
public class HelloController {
@ApiOperation("获取列表方法")
@RequestMapping(value = "/getlist",method = RequestMethod.GET)
public String getlist(){
return "getlist";
}
}
4:访问Knife4j页面
直接访问Knife4j的页面：http://ip:prot/doc.html
4、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() {
// ...
}
5、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 文档。
扫一扫
581
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
