Swagger配置请求示例实战教程打造专业易读的API文档提升开发效率

威震华夏关云长

引言

在当今快速发展的软件开发行业中，API（应用程序编程接口）已经成为连接不同系统和服务的桥梁。随着微服务架构的普及，API的数量和复杂性不断增加，如何有效地管理和文档化这些API成为开发团队面临的重要挑战。Swagger（现已更名为OpenAPI）作为一个强大的API文档工具，能够帮助开发者自动生成、描述、调用和可视化RESTful风格的Web服务，极大地提升了API开发和维护的效率。

本文将详细介绍如何配置Swagger并添加请求示例，帮助您打造专业、易读的API文档，从而提升整个开发团队的工作效率。我们将从基础概念入手，逐步深入到高级配置和实战案例，确保您能够全面掌握Swagger的使用技巧。

Swagger基础

什么是Swagger

Swagger是一套围绕OpenAPI规范构建的开源工具，可以帮助您设计、构建、记录和使用RESTful Web服务。它主要包括以下几个部分：

• Swagger Editor：基于浏览器的编辑器，可以在其中编写OpenAPI规范。
• Swagger UI：将OpenAPI规范呈现为交互式API文档。
• Swagger Codegen：根据OpenAPI规范生成服务器存根和客户端库。
• Swagger Core：与Java等编程语言集成的库，用于创建OpenAPI规范。

OpenAPI规范

OpenAPI规范（OAS）是Linux基金会下的一个项目，它定义了一个标准的、与语言无关的接口描述RESTful API。OpenAPI文档使团队能够在不查看实际源代码的情况下理解和调用API。

Swagger的优势

使用Swagger具有以下优势：

1. 自动化文档生成：减少手动编写和维护文档的工作量。
2. 交互式API探索：开发者可以直接在文档中测试API端点。
3. 客户端代码生成：可以自动生成多种编程语言的客户端代码。
4. API设计优先：可以在编码前设计API，促进团队协作。
5. 提高开发效率：减少前后端沟通成本，加速开发流程。

环境搭建

在Spring Boot项目中集成Swagger

对于Java开发者来说，将Swagger集成到Spring Boot项目中最常用的库是Springfox。以下是集成步骤：

首先，在您的pom.xml文件中添加Springfox依赖：

2. <dependency>
3.     <groupId>io.springfox</groupId>
4.     <artifactId>springfox-swagger2</artifactId>
5.     <version>3.0.0</version>
6. </dependency>
7. <dependency>
8.     <groupId>io.springfox</groupId>
9.     <artifactId>springfox-swagger-ui</artifactId>
10.     <version>3.0.0</version>
11. </dependency>

复制代码

如果您使用的是Spring Boot 2.6.x或更高版本，还需要添加以下配置以解决路径匹配问题：

2. @Configuration
3. public class WebConfig implements WebMvcConfigurer {
4.     @Override
5.     public void configurePathMatch(PathMatchConfigurer configurer) {
6.         configurer.addPathPrefix("/api", Pattern.compile("/api"));
7.     }
8. }

复制代码

创建一个配置类来启用Swagger：

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.    
6.     @Bean
7.     public Docket api() {
8.         return new Docket(DocumentationType.SWAGGER_2)
9.                 .select()
10.                 .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
11.                 .paths(PathSelectors.any())
12.                 .build();
13.     }
14. }

复制代码

启动应用程序后，您可以通过访问以下URL来查看Swagger UI：

2. http://localhost:8080/swagger-ui.html

复制代码

在其他框架中的集成

在Node.js的Express框架中，您可以使用swagger-ui-express和swagger-jsdoc来集成Swagger：

2. const express = require('express');
3. const swaggerUi = require('swagger-ui-express');
4. const swaggerJsdoc = require('swagger-jsdoc');
6. const app = express();
8. const options = {
9.   definition: {
10.     openapi: '3.0.0',
11.     info: {
12.       title: 'My API',
13.       version: '1.0.0',
14.     },
15.   },
16.   apis: ['./routes/*.js'], // 包含API注解的文件路径
17. };
19. const specs = swaggerJsdoc(options);
20. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
22. // ... 其他路由和中间件
24. app.listen(3000, () => {
25.   console.log('Server is running on port 3000');
26. });

复制代码

在Python的Flask框架中，您可以使用flask-swagger-ui：

2. from flask import Flask
3. from flask_swagger_ui import get_swaggerui_blueprint
5. app = Flask(__name__)
7. SWAGGER_URL = '/api/docs'  # Swagger UI的URL
8. API_URL = '/static/swagger.json'  # API文档文件的URL
10. swaggerui_blueprint = get_swaggerui_blueprint(
11.     SWAGGER_URL,
12.     API_URL,
13.     config={
14.         'app_name': "My API"
15.     }
16. )
18. app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)
20. if __name__ == '__main__':
21.     app.run(debug=True)

复制代码

基础配置

Docket配置详解

在Spring Boot中，Docket是Swagger的核心配置类，它允许您自定义Swagger的行为。以下是一些常用的配置选项：

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.    
6.     @Bean
7.     public Docket api() {
8.         return new Docket(DocumentationType.SWAGGER_2)
9.                 .apiInfo(apiInfo()) // API基本信息
10.                 .select()
11.                 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 控制器包路径
12.                 .paths(PathSelectors.any()) // 所有路径
13.                 .build()
14.                 .produces(Collections.singleton("application/json")) // 生成的内容类型
15.                 .consumes(Collections.singleton("application/json")) // 接受的内容类型
16.                 .protocols(Collections.singleton("http")) // 支持的协议
17.                 .securitySchemes(Collections.singletonList(apiKey())) // 安全方案
18.                 .securityContexts(Collections.singletonList(securityContext())); // 安全上下文
19.     }
20.    
21.     private ApiInfo apiInfo() {
22.         return new ApiInfoBuilder()
23.                 .title("示例API文档")
24.                 .description("这是一个示例API的文档")
25.                 .version("1.0.0")
26.                 .contact(new Contact("开发者姓名", "https://example.com", "developer@example.com"))
27.                 .license("Apache License Version 2.0")
28.                 .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
29.                 .build();
30.     }
31.    
32.     private ApiKey apiKey() {
33.         return new ApiKey("JWT", "Authorization", "header");
34.     }
35.    
36.     private SecurityContext securityContext() {
37.         return SecurityContext.builder()
38.                 .securityReferences(defaultAuth())
39.                 .forPaths(PathSelectors.regex("/api/.*"))
40.                 .build();
41.     }
42.    
43.     private List<SecurityReference> defaultAuth() {
44.         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
45.         return Collections.singletonList(new SecurityReference("JWT", new AuthorizationScope[]{authorizationScope}));
46.     }
47. }

复制代码

全局参数配置

您可以为所有API请求添加全局参数，例如认证头：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .globalOperationParameters(
6.                 Collections.singletonList(
7.                     new ParameterBuilder()
8.                         .name("Authorization")
9.                         .description("认证令牌")
10.                         .modelRef(new ModelRef("string"))
11.                         .parameterType("header")
12.                         .required(true)
13.                         .build()
14.                 )
15.             )
16.             // ... 其他配置
17.             .build();
18. }

复制代码

全局响应配置

您可以为所有API响应添加全局响应消息：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .globalResponseMessage(RequestMethod.GET,
6.                 Collections.singletonList(
7.                     new ResponseMessageBuilder()
8.                         .code(500)
9.                         .message("服务器错误")
10.                         .responseModel(new ModelRef("Error"))
11.                         .build()
12.                 )
13.             )
14.             // ... 其他配置
15.             .build();
16. }

复制代码

注解详解

Swagger提供了一系列注解，帮助您丰富API文档的内容。下面详细介绍常用注解及其使用方法。

API级别注解

用于标记Controller类作为Swagger文档的资源。

2. @Api(tags = "用户管理", description = "提供用户的增删改查功能")
3. @RestController
4. @RequestMapping("/api/users")
5. public class UserController {
6.     // ...
7. }

复制代码

用于对API进行排序，这在有多个Controller时特别有用。

2. @ApiSort(1)
3. @Api(tags = "用户管理")
4. @RestController
5. @RequestMapping("/api/users")
6. public class UserController {
7.     // ...
8. }

复制代码

方法级别注解

用于描述一个方法或API操作。

2. @ApiOperation(
3.     value = "获取用户列表",
4.     notes = "获取系统中所有用户的列表，支持分页",
5.     response = User.class,
6.     responseContainer = "List",
7.     tags = {"用户管理"}
8. )
9. @GetMapping
10. public ResponseEntity<List<User>> getAllUsers() {
11.     // ...
12. }

复制代码

用于描述方法的参数。

2. @ApiImplicitParams({
3.     @ApiImplicitParam(
4.         name = "page",
5.         value = "页码",
6.         required = true,
7.         dataType = "int",
8.         paramType = "query",
9.         defaultValue = "1"
10.     ),
11.     @ApiImplicitParam(
12.         name = "size",
13.         value = "每页大小",
14.         required = true,
15.         dataType = "int",
16.         paramType = "query",
17.         defaultValue = "10"
18.     )
19. })
20. @GetMapping
21. public ResponseEntity<List<User>> getUsersByPage(@RequestParam int page, @RequestParam int size) {
22.     // ...
23. }

复制代码

用于描述方法可能的响应。

2. @ApiResponses(value = {
3.     @ApiResponse(code = 200, message = "成功获取用户", response = User.class),
4.     @ApiResponse(code = 401, message = "未授权"),
5.     @ApiResponse(code = 403, message = "禁止访问"),
6.     @ApiResponse(code = 404, message = "用户不存在"),
7.     @ApiResponse(code = 500, message = "服务器错误")
8. })
9. @GetMapping("/{id}")
10. public ResponseEntity<User> getUserById(@PathVariable Long id) {
11.     // ...
12. }

复制代码

模型注解

用于描述模型（通常是实体类）。

2. @ApiModel(description = "用户详细信息")
3. public class User {
4.     // ...
5. }

复制代码

用于描述模型属性。

2. public class User {
3.     @ApiModelProperty(value = "用户ID", example = "1", required = true)
4.     private Long id;
5.    
6.     @ApiModelProperty(value = "用户名", example = "john_doe", required = true)
7.     private String username;
8.    
9.     @ApiModelProperty(value = "电子邮箱", example = "john@example.com", required = true)
10.     private String email;
11.    
12.     @ApiModelProperty(value = "密码", example = "password123", required = true, accessMode = ApiModelProperty.AccessMode.WRITE_ONLY)
13.     private String password;
14.    
15.     @ApiModelProperty(value = "创建时间", example = "2023-01-01T00:00:00Z", readOnly = true)
16.     private Date createdAt;
17.    
18.     // getters and setters
19. }

复制代码

请求和响应注解

当使用@RequestBody时，可以结合@ApiParam提供更详细的描述。

2. @ApiOperation(value = "创建新用户")
3. @PostMapping
4. public ResponseEntity<User> createUser(
5.     @ApiParam(value = "用户对象", required = true) @Valid @RequestBody UserDto userDto) {
6.     // ...
7. }

复制代码

用于忽略某个方法或参数，使其不出现在API文档中。

2. @ApiIgnore
3. @GetMapping("/internal")
4. public String internalMethod() {
5.     return "This is an internal method";
6. }

复制代码

请求示例配置

请求示例是API文档中非常重要的一部分，它可以帮助开发者快速了解如何正确地调用API。下面介绍如何在Swagger中配置请求示例。

使用@ApiModelProperty添加示例值

最简单的方式是在@ApiModelProperty注解中直接提供example属性：

2. public class UserDto {
3.     @ApiModelProperty(value = "用户名", example = "john_doe", required = true)
4.     private String username;
5.    
6.     @ApiModelProperty(value = "电子邮箱", example = "john@example.com", required = true)
7.     private String email;
8.    
9.     @ApiModelProperty(value = "年龄", example = "30")
10.     private Integer age;
11.    
12.     // getters and setters
13. }

复制代码

使用@Example和@ExampleProperty

对于更复杂的示例，可以使用@Example和@ExampleProperty注解：

2. @ApiOperation(value = "创建用户", notes = "创建一个新用户")
3. @ApiResponses(value = {
4.     @ApiResponse(code = 201, message = "用户创建成功",
5.         examples = @Example(value = {
6.             @ExampleProperty(mediaType = "application/json", value = "{"id": 1, "username": "john_doe", "email": "john@example.com"}")
7.         })
8.     )
9. })
10. @PostMapping
11. public ResponseEntity<User> createUser(@Valid @RequestBody UserDto userDto) {
12.     // ...
13. }

复制代码

在@ApiOperation中添加示例

您可以在@ApiOperation注解中直接添加示例：

2. @ApiOperation(
3.     value = "更新用户",
4.     notes = "更新指定ID的用户信息",
5.     examples = @Example(value = {
6.         @ExampleProperty(mediaType = "application/json", value = "{"username": "new_username", "email": "new_email@example.com"}")
7.     })
8. )
9. @PutMapping("/{id}")
10. public ResponseEntity<User> updateUser(
11.     @ApiParam(value = "用户ID", example = "1") @PathVariable Long id,
12.     @Valid @RequestBody UserDto userDto) {
13.     // ...
14. }

复制代码

使用@RequestPart和@ExampleProperty处理文件上传

对于文件上传接口，可以使用@RequestPart和@ExampleProperty：

2. @ApiOperation(value = "上传用户头像")
3. @ApiResponses(value = {
4.     @ApiResponse(code = 200, message = "上传成功",
5.         examples = @Example(value = {
6.             @ExampleProperty(mediaType = "application/json", value = "{"url": "https://example.com/avatar.jpg"}")
7.         })
8.     )
9. })
10. @PostMapping("/{id}/avatar")
11. public ResponseEntity<Map<String, String>> uploadAvatar(
12.     @ApiParam(value = "用户ID", example = "1") @PathVariable Long id,
13.     @ApiParam(value = "头像文件", required = true) @RequestPart("file") MultipartFile file) {
14.     // ...
15. }

复制代码

使用Swagger配置类添加全局示例

您可以在Swagger配置类中添加全局示例：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .globalRequestParameters(Collections.singletonList(
6.                 new ParameterBuilder()
7.                     .name("Authorization")
8.                     .description("认证令牌")
9.                     .modelRef(new ModelRef("string"))
10.                     .parameterType("header")
11.                     .required(true)
12.                     .example("Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
13.                     .build()
14.             ))
15.             // ... 其他配置
16.             .build();
17. }

复制代码

使用@Operation和@RequestBody（OpenAPI 3.0）

如果您使用的是OpenAPI 3.0，可以使用@Operation和@RequestBody注解：

2. @Operation(
3.     summary = "创建用户",
4.     description = "创建一个新用户",
5.     requestBody = @RequestBody(
6.         description = "用户对象",
7.         required = true,
8.         content = @Content(
9.             mediaType = "application/json",
10.             schema = @Schema(implementation = UserDto.class),
11.             examples = {
12.                 @ExampleObject(
13.                     name = "示例1",
14.                     description = "一个普通的用户示例",
15.                     value = "{"username": "john_doe", "email": "john@example.com", "age": 30}"
16.                 ),
17.                 @ExampleObject(
18.                     name = "示例2",
19.                     description = "一个包含所有字段的用户示例",
20.                     value = "{"username": "jane_doe", "email": "jane@example.com", "age": 25, "phone": "1234567890"}"
21.                 )
22.             }
23.         )
24.     )
25. )
26. @PostMapping
27. public ResponseEntity<User> createUser(@Valid @RequestBody UserDto userDto) {
28.     // ...
29. }

复制代码

动态生成请求示例

有时您可能需要根据不同的条件动态生成请求示例。这时，您可以创建一个自定义的示例提供器：

2. public class UserExampleProvider {
3.    
4.     public static User getExampleUser() {
5.         User user = new User();
6.         user.setId(1L);
7.         user.setUsername("john_doe");
8.         user.setEmail("john@example.com");
9.         user.setAge(30);
10.         user.setCreatedAt(new Date());
11.         return user;
12.     }
13.    
14.     public static List<User> getExampleUserList() {
15.         List<User> users = new ArrayList<>();
16.         users.add(getExampleUser());
17.         
18.         User user2 = new User();
19.         user2.setId(2L);
20.         user2.setUsername("jane_doe");
21.         user2.setEmail("jane@example.com");
22.         user2.setAge(25);
23.         user2.setCreatedAt(new Date());
24.         users.add(user2);
25.         
26.         return users;
27.     }
28. }

复制代码

然后在控制器中使用这些示例：

2. @ApiOperation(
3.     value = "获取用户列表",
4.     notes = "获取系统中所有用户的列表",
5.     response = User.class,
6.     responseContainer = "List"
7. )
8. @GetMapping
9. public ResponseEntity<List<User>> getAllUsers() {
10.     // 实际实现...
11.     // 这里只是一个示例，展示如何使用示例提供器
12.     return ResponseEntity.ok(UserExampleProvider.getExampleUserList());
13. }

复制代码

高级功能

API分组

在大型项目中，您可能需要将API文档分组，以便更好地组织和管理。Swagger提供了分组功能，允许您根据不同的标准（如模块、版本等）对API进行分组。

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.    
6.     @Bean
7.     public Docket publicApi() {
8.         return new Docket(DocumentationType.SWAGGER_2)
9.                 .groupName("public-api")
10.                 .select()
11.                 .apis(RequestHandlerSelectors.basePackage("com.example.controller.public"))
12.                 .paths(PathSelectors.any())
13.                 .build()
14.                 .apiInfo(publicApiInfo());
15.     }
16.    
17.     @Bean
18.     public Docket adminApi() {
19.         return new Docket(DocumentationType.SWAGGER_2)
20.                 .groupName("admin-api")
21.                 .select()
22.                 .apis(RequestHandlerSelectors.basePackage("com.example.controller.admin"))
23.                 .paths(PathSelectors.any())
24.                 .build()
25.                 .apiInfo(adminApiInfo())
26.                 .securitySchemes(Collections.singletonList(apiKey()))
27.                 .securityContexts(Collections.singletonList(securityContext()));
28.     }
29.    
30.     private ApiInfo publicApiInfo() {
31.         return new ApiInfoBuilder()
32.                 .title("公共API文档")
33.                 .description "系统公共接口文档")
34.                 .version("1.0.0")
35.                 .build();
36.     }
37.    
38.     private ApiInfo adminApiInfo() {
39.         return new ApiInfoBuilder()
40.                 .title("管理API文档")
41.                 .description("系统管理接口文档")
42.                 .version("1.0.0")
43.                 .build();
44.     }
45.    
46.     // 其他方法...
47. }

复制代码

自定义Swagger UI

您可以通过自定义配置来改变Swagger UI的外观和行为。创建一个WebMvcConfigurer来添加自定义资源：

2. @Configuration
3. public class WebMvcConfig implements WebMvcConfigurer {
4.    
5.     @Override
6.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
7.         registry.addResourceHandler("swagger-ui.html")
8.                 .addResourceLocations("classpath:/META-INF/resources/");
9.         
10.         registry.addResourceHandler("/webjars/**")
11.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
12.     }
13. }

复制代码

然后，您可以创建一个自定义的Swagger UI页面：

2. <!DOCTYPE html>
3. <html>
4. <head>
5.     <meta charset="UTF-8">
6.     <title>自定义Swagger UI</title>
7.     <link rel="stylesheet" type="text/css" href="./webjars/swagger-ui/dist/swagger-ui.css" />
8.     <link rel="stylesheet" type="text/css" href="./css/custom-swagger.css" />
9.     <style>
10.         html {
11.             box-sizing: border-box;
12.             overflow: -moz-scrollbars-vertical;
13.             overflow-y: scroll;
14.         }
15.         *, *:before, *:after {
16.             box-sizing: inherit;
17.         }
18.         body {
19.             margin: 0;
20.             background: #fafafa;
21.         }
22.     </style>
23. </head>
24. <body>
25.     <div id="swagger-ui"></div>
26.     <script src="./webjars/swagger-ui/dist/swagger-ui-bundle.js"></script>
27.     <script src="./webjars/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
28.     <script>
29.         window.onload = function() {
30.             const ui = SwaggerUIBundle({
31.                 url: "/v2/api-docs",
32.                 dom_id: '#swagger-ui',
33.                 deepLinking: true,
34.                 presets: [
35.                     SwaggerUIBundle.presets.apis,
36.                     SwaggerUIStandalonePreset
37.                 ],
38.                 plugins: [
39.                     SwaggerUIBundle.plugins.DownloadUrl
40.                 ],
41.                 layout: "StandaloneLayout",
42.                 validatorUrl: null,
43.                 supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
44.                 docExpansion: "none",
45.                 defaultModelsExpandDepth: -1,
46.                 displayRequestDuration: true,
47.                 filter: true,
48.                 persistAuthorization: true
49.             });
50.         };
51.     </script>
52. </body>
53. </html>

复制代码

集成Spring Security

如果您的应用使用了Spring Security，您需要配置Swagger UI可以访问的端点：

2. @Configuration
3. @EnableWebSecurity
4. public class SecurityConfig extends WebSecurityConfigurerAdapter {
5.    
6.     @Override
7.     protected void configure(HttpSecurity http) throws Exception {
8.         http
9.             .authorizeRequests()
10.                 .antMatchers("/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**").permitAll()
11.                 .anyRequest().authenticated()
12.             .and()
13.             .csrf().disable();
14.     }
15. }

复制代码

多环境配置

您可能希望在不同的环境中使用不同的Swagger配置。可以通过Spring Profile实现：

2. @Configuration
3. @Profile({"dev", "test"})
4. @EnableSwagger2
5. public class SwaggerConfig {
6.    
7.     @Bean
8.     public Docket api() {
9.         return new Docket(DocumentationType.SWAGGER_2)
10.                 .select()
11.                 .apis(RequestHandlerSelectors.any())
12.                 .paths(PathSelectors.any())
13.                 .build();
14.     }
15. }

复制代码

然后在application.properties中指定活动Profile：

2. spring.profiles.active=dev

复制代码

API版本控制

随着API的演进，您可能需要支持多个版本的API。Swagger可以帮助您实现这一点：

2. @Configuration
3. @EnableSwagger2
4. public class SwaggerConfig {
5.    
6.     @Bean
7.     public Docket apiV1() {
8.         return new Docket(DocumentationType.SWAGGER_2)
9.                 .groupName("v1")
10.                 .select()
11.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiV1.class))
12.                 .build()
13.                 .apiInfo(apiV1Info());
14.     }
15.    
16.     @Bean
17.     public Docket apiV2() {
18.         return new Docket(DocumentationType.SWAGGER_2)
19.                 .groupName("v2")
20.                 .select()
21.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiV2.class))
22.                 .build()
23.                 .apiInfo(apiV2Info());
24.     }
25.    
26.     private ApiInfo apiV1Info() {
27.         return new ApiInfoBuilder()
28.                 .title("API V1文档")
29.                 .version("1.0.0")
30.                 .build();
31.     }
32.    
33.     private ApiInfo apiV2Info() {
34.         return new ApiInfoBuilder()
35.                 .title("API V2文档")
36.                 .version("2.0.0")
37.                 .build();
38.     }
39. }

复制代码

然后创建自定义注解来标记不同版本的API：

2. @Target({ElementType.METHOD, ElementType.TYPE})
3. @Retention(RetentionPolicy.RUNTIME)
4. public @interface ApiV1 {
5. }
7. @Target({ElementType.METHOD, ElementType.TYPE})
8. @Retention(RetentionPolicy.RUNTIME)
9. public @interface ApiV2 {
10. }

复制代码

在控制器中使用这些注解：

2. @ApiV1
3. @GetMapping("/v1/users")
4. public ResponseEntity<List<User>> getUsersV1() {
5.     // V1实现
6. }
8. @ApiV2
9. @GetMapping("/v2/users")
10. public ResponseEntity<List<UserDto>> getUsersV2() {
11.     // V2实现
12. }

复制代码

最佳实践

1. 保持文档与代码同步

Swagger最大的优势之一是能够保持文档与代码同步。为了充分利用这一点：

• 使用注解来描述API，而不是单独维护文档文件。
• 在API变更时，同时更新相关的Swagger注解。
• 将API文档检查纳入CI/CD流程，确保文档始终是最新的。

2. 提供清晰且有意义的描述

为API、参数和模型提供清晰且有意义的描述：

2. @ApiOperation(
3.     value = "创建新用户",
4.     notes = "创建一个新用户账户。用户名必须是唯一的，电子邮件地址必须是有效的格式。密码必须至少包含8个字符，包括至少一个大写字母、一个小写字母和一个数字。"
5. )
6. @PostMapping
7. public ResponseEntity<User> createUser(@Valid @RequestBody UserDto userDto) {
8.     // ...
9. }

复制代码

3. 使用适当的HTTP状态码

使用标准HTTP状态码来表示操作结果：

2. @ApiResponses(value = {
3.     @ApiResponse(code = 201, message = "用户创建成功", response = User.class),
4.     @ApiResponse(code = 400, message = "无效的输入数据"),
5.     @ApiResponse(code = 409, message = "用户名或电子邮件已存在"),
6.     @ApiResponse(code = 500, message = "服务器错误")
7. })
8. @PostMapping
9. public ResponseEntity<User> createUser(@Valid @RequestBody UserDto userDto) {
10.     // ...
11. }

复制代码

4. 提供真实且有意义的示例

提供真实且有意义的请求和响应示例，而不是无意义的占位符：

2. public class UserDto {
3.     @ApiModelProperty(
4.         value = "用户名",
5.         example = "john_doe",
6.         required = true,
7.         notes = "用户名必须是唯一的，只能包含字母、数字和下划线，长度在3到20个字符之间。"
8.     )
9.     private String username;
10.    
11.     @ApiModelProperty(
12.         value = "电子邮箱",
13.         example = "john@example.com",
14.         required = true,
15.         notes = "必须是有效的电子邮件地址格式。"
16.     )
17.     private String email;
18.    
19.     // ...
20. }

复制代码

5. 使用DTO而不是实体类

在API中使用DTO（数据传输对象）而不是直接使用实体类，这样可以：

• 隐藏不想暴露的字段（如密码哈希）。
• 提供更适合API需求的字段结构。
• 避免因实体类变更而影响API兼容性。

2. @ApiModel(description = "用户数据传输对象")
3. public class UserDto {
4.     @ApiModelProperty(value = "用户ID", example = "1", readOnly = true)
5.     private Long id;
6.    
7.     @ApiModelProperty(value = "用户名", example = "john_doe", required = true)
8.     private String username;
9.    
10.     @ApiModelProperty(value = "电子邮箱", example = "john@example.com", required = true)
11.     private String email;
12.    
13.     // 不包含密码等敏感字段
14.    
15.     // getters and setters
16. }

复制代码

6. 合理使用分组和标签

对于大型项目，使用分组和标签来组织API文档：

2. @Api(tags = {"用户管理", "核心功能"})
3. @RestController
4. @RequestMapping("/api/users")
5. public class UserController {
6.     // ...
7. }

复制代码

7. 添加认证信息

如果API需要认证，确保在文档中明确说明：

2. @Bean
3. public Docket api() {
4.     return new Docket(DocumentationType.SWAGGER_2)
5.             .securitySchemes(Collections.singletonList(apiKey()))
6.             .securityContexts(Collections.singletonList(securityContext()))
7.             // ... 其他配置
8.             .build();
9. }
11. private ApiKey apiKey() {
12.     return new ApiKey("JWT", "Authorization", "header");
13. }
15. private SecurityContext securityContext() {
16.     return SecurityContext.builder()
17.             .securityReferences(defaultAuth())
18.             .forPaths(PathSelectors.regex("/api/.*"))
19.             .build();
20. }
22. private List<SecurityReference> defaultAuth() {
23.     AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
24.     return Collections.singletonList(new SecurityReference("JWT", new AuthorizationScope[]{authorizationScope}));
25. }

复制代码

8. 在生产环境中禁用Swagger

出于安全考虑，应该在生产环境中禁用Swagger：

2. @Configuration
3. @Profile({"dev", "test"})
4. @EnableSwagger2
5. public class SwaggerConfig {
6.     // ...
7. }

复制代码

或者使用条件配置：

2. @Bean
3. @ConditionalOnProperty(name = "swagger.enabled", havingValue = "true")
4. public Docket api() {
5.     return new Docket(DocumentationType.SWAGGER_2)
6.             // ...
7.             .build();
8. }

复制代码

然后在application.properties中：

2. # 开发和测试环境
3. swagger.enabled=true
5. # 生产环境
6. # swagger.enabled=false

复制代码

9. 使用外部化配置

对于复杂的Swagger配置，考虑使用外部化配置：

2. @Configuration
3. @EnableSwagger2
4. @ConfigurationProperties(prefix = "swagger")
5. public class SwaggerConfig {
6.     private String title;
7.     private String description;
8.     private String version;
9.     private Contact contact;
10.    
11.     @Bean
12.     public Docket api() {
13.         return new Docket(DocumentationType.SWAGGER_2)
14.                 .apiInfo(new ApiInfoBuilder()
15.                         .title(title)
16.                         .description(description)
17.                         .version(version)
18.                         .contact(contact)
19.                         .build())
20.                 // ... 其他配置
21.                 .build();
22.     }
23.    
24.     // getters and setters
25. }

复制代码

然后在application.yml中：

2. swagger:
3.   title: "我的API文档"
4.   description: "这是一个示例API的文档"
5.   version: "1.0.0"
6.   contact:
7.     name: "开发者姓名"
8.     email: "developer@example.com"
9.     url: "https://example.com"

复制代码

10. 定期审查和更新文档

定期审查和更新API文档，确保其准确性和完整性：

• 将文档审查纳入开发流程。
• 在API变更时，评估是否需要更新文档。
• 收集用户反馈，持续改进文档质量。

实战案例

让我们通过一个完整的示例来展示如何使用Swagger创建专业、易读的API文档。我们将创建一个简单的博客系统API，包括用户管理、文章管理和评论管理功能。

项目结构

2. src/main/java/com/example/blog/
3. ├── config/
4. │   └── SwaggerConfig.java
5. ├── controller/
6. │   ├── AuthController.java
7. │   ├── PostController.java
8. │   ├── CommentController.java
9. │   └── UserController.java
10. ├── dto/
11. │   ├── request/
12. │   │   ├── CreateUserRequest.java
13. │   │   ├── CreatePostRequest.java
14. │   │   ├── CreateCommentRequest.java
15. │   │   └── LoginRequest.java
16. │   └── response/
17. │       ├── UserResponse.java
18. │       ├── PostResponse.java
19. │       └── CommentResponse.java
20. ├── model/
21. │   ├── User.java
22. │   ├── Post.java
23. │   └── Comment.java
24. ├── repository/
25. │   ├── UserRepository.java
26. │   ├── PostRepository.java
27. │   └── CommentRepository.java
28. ├── security/
29. │   ├── JwtTokenProvider.java
30. │   └── JwtAuthenticationFilter.java
31. └── BlogApplication.java

复制代码

依赖配置

首先，在pom.xml中添加必要的依赖：

2. <dependencies>
3.     <!-- Spring Boot Starter Web -->
4.     <dependency>
5.         <groupId>org.springframework.boot</groupId>
6.         <artifactId>spring-boot-starter-web</artifactId>
7.     </dependency>
8.    
9.     <!-- Spring Boot Starter Data JPA -->
10.     <dependency>
11.         <groupId>org.springframework.boot</groupId>
12.         <artifactId>spring-boot-starter-data-jpa</artifactId>
13.     </dependency>
14.    
15.     <!-- Spring Boot Starter Security -->
16.     <dependency>
17.         <groupId>org.springframework.boot</groupId>
18.         <artifactId>spring-boot-starter-security</artifactId>
19.     </dependency>
20.    
21.     <!-- Spring Boot Starter Validation -->
22.     <dependency>
23.         <groupId>org.springframework.boot</groupId>
24.         <artifactId>spring-boot-starter-validation</artifactId>
25.     </dependency>
26.    
27.     <!-- H2 Database -->
28.     <dependency>
29.         <groupId>com.h2database</groupId>
30.         <artifactId>h2</artifactId>
31.         <scope>runtime</scope>
32.     </dependency>
33.    
34.     <!-- JWT -->
35.     <dependency>
36.         <groupId>io.jsonwebtoken</groupId>
37.         <artifactId>jjwt-api</artifactId>
38.         <version>0.11.5</version>
39.     </dependency>
40.     <dependency>
41.         <groupId>io.jsonwebtoken</groupId>
42.         <artifactId>jjwt-impl</artifactId>
43.         <version>0.11.5</version>
44.         <scope>runtime</scope>
45.     </dependency>
46.     <dependency>
47.         <groupId>io.jsonwebtoken</groupId>
48.         <artifactId>jjwt-jackson</artifactId>
49.         <version>0.11.5</version>
50.         <scope>runtime</scope>
51.     </dependency>
52.    
53.     <!-- Swagger -->
54.     <dependency>
55.         <groupId>io.springfox</groupId>
56.         <artifactId>springfox-swagger2</artifactId>
57.         <version>3.0.0</version>
58.     </dependency>
59.     <dependency>
60.         <groupId>io.springfox</groupId>
61.         <artifactId>springfox-swagger-ui</artifactId>
62.         <version>3.0.0</version>
63.     </dependency>
64.    
65.     <!-- Lombok -->
66.     <dependency>
67.         <groupId>org.projectlombok</groupId>
68.         <artifactId>lombok</artifactId>
69.         <optional>true</optional>
70.     </dependency>
71. </dependencies>

复制代码

Swagger配置

创建Swagger配置类：

2. package com.example.blog.config;
4. import com.example.blog.security.JwtTokenProvider;
5. import org.springframework.context.annotation.Bean;
6. import org.springframework.context.annotation.Configuration;
7. import springfox.documentation.builders.ApiInfoBuilder;
8. import springfox.documentation.builders.PathSelectors;
9. import springfox.documentation.builders.RequestHandlerSelectors;
10. import springfox.documentation.service.*;
11. import springfox.documentation.spi.DocumentationType;
12. import springfox.documentation.spi.service.contexts.SecurityContext;
13. import springfox.documentation.spring.web.plugins.Docket;
14. import springfox.documentation.swagger2.annotations.EnableSwagger2;
16. import java.util.Arrays;
17. import java.util.Collections;
18. import java.util.List;
20. @Configuration
21. @EnableSwagger2
22. public class SwaggerConfig {
24.     @Bean
25.     public Docket api() {
26.         return new Docket(DocumentationType.SWAGGER_2)
27.                 .select()
28.                 .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller"))
29.                 .paths(PathSelectors.any())
30.                 .build()
31.                 .apiInfo(apiInfo())
32.                 .securityContexts(Collections.singletonList(securityContext()))
33.                 .securitySchemes(Collections.singletonList(apiKey()))
34.                 .produces(Collections.singleton("application/json"))
35.                 .consumes(Collections.singleton("application/json"));
36.     }
38.     private ApiInfo apiInfo() {
39.         return new ApiInfoBuilder()
40.                 .title("博客系统API文档")
41.                 .description("这是一个博客系统的RESTful API文档，提供了用户管理、文章管理和评论管理等功能。")
42.                 .version("1.0.0")
43.                 .contact(new Contact("博客开发团队", "https://blog.example.com", "dev@blog.example.com"))
44.                 .license("MIT License")
45.                 .licenseUrl("https://opensource.org/licenses/MIT")
46.                 .build();
47.     }
49.     private ApiKey apiKey() {
50.         return new ApiKey("JWT", "Authorization", "header");
51.     }
53.     private SecurityContext securityContext() {
54.         return SecurityContext.builder()
55.                 .securityReferences(defaultAuth())
56.                 .forPaths(PathSelectors.regex("/api/.*"))
57.                 .build();
58.     }
60.     private List<SecurityReference> defaultAuth() {
61.         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
62.         return Collections.singletonList(new SecurityReference("JWT", new AuthorizationScope[]{authorizationScope}));
63.     }
64. }

复制代码

模型类

定义用户模型：

2. package com.example.blog.model;
4. import lombok.AllArgsConstructor;
5. import lombok.Data;
6. import lombok.NoArgsConstructor;
8. import javax.persistence.*;
9. import javax.validation.constraints.Email;
10. import javax.validation.constraints.NotBlank;
11. import javax.validation.constraints.Size;
12. import java.time.LocalDateTime;
13. import java.util.HashSet;
14. import java.util.Set;
16. @Entity
17. @Table(name = "users")
18. @Data
19. @NoArgsConstructor
20. @AllArgsConstructor
21. public class User {
22.     @Id
23.     @GeneratedValue(strategy = GenerationType.IDENTITY)
24.     private Long id;
26.     @NotBlank
27.     @Size(min = 3, max = 20)
28.     @Column(unique = true)
29.     private String username;
31.     @NotBlank
32.     @Size(max = 50)
33.     @Email
34.     @Column(unique = true)
35.     private String email;
37.     @NotBlank
38.     @Size(min = 6, max = 100)
39.     private String password;
41.     @Column(name = "created_at")
42.     private LocalDateTime createdAt;
44.     @Column(name = "updated_at")
45.     private LocalDateTime updatedAt;
47.     @ElementCollection(fetch = FetchType.EAGER)
48.     @Enumerated(EnumType.STRING)
49.     private Set<Role> roles = new HashSet<>();
51.     public User(String username, String email, String password) {
52.         this.username = username;
53.         this.email = email;
54.         this.password = password;
55.         this.createdAt = LocalDateTime.now();
56.         this.updatedAt = LocalDateTime.now();
57.         this.roles.add(Role.ROLE_USER);
58.     }
60.     public enum Role {
61.         ROLE_USER,
62.         ROLE_ADMIN
63.     }
64. }

复制代码

定义文章模型：

2. package com.example.blog.model;
4. import lombok.AllArgsConstructor;
5. import lombok.Data;
6. import lombok.NoArgsConstructor;
8. import javax.persistence.*;
9. import javax.validation.constraints.NotBlank;
10. import javax.validation.constraints.Size;
11. import java.time.LocalDateTime;
12. import java.util.HashSet;
13. import java.util.Set;
15. @Entity
16. @Table(name = "posts")
17. @Data
18. @NoArgsConstructor
19. @AllArgsConstructor
20. public class Post {
21.     @Id
22.     @GeneratedValue(strategy = GenerationType.IDENTITY)
23.     private Long id;
25.     @NotBlank
26.     @Size(min = 1, max = 100)
27.     private String title;
29.     @NotBlank
30.     @Size(min = 1, max = 5000)
31.     private String content;
33.     @Column(name = "created_at")
34.     private LocalDateTime createdAt;
36.     @Column(name = "updated_at")
37.     private LocalDateTime updatedAt;
39.     @ManyToOne(fetch = FetchType.LAZY)
40.     @JoinColumn(name = "author_id")
41.     private User author;
43.     @OneToMany(mappedBy = "post", cascade = CascadeType.ALL, orphanRemoval = true)
44.     private Set<Comment> comments = new HashSet<>();
46.     public Post(String title, String content, User author) {
47.         this.title = title;
48.         this.content = content;
49.         this.author = author;
50.         this.createdAt = LocalDateTime.now();
51.         this.updatedAt = LocalDateTime.now();
52.     }
53. }

复制代码

定义评论模型：

2. package com.example.blog.model;
4. import lombok.AllArgsConstructor;
5. import lombok.Data;
6. import lombok.NoArgsConstructor;
8. import javax.persistence.*;
9. import javax.validation.constraints.NotBlank;
10. import javax.validation.constraints.Size;
11. import java.time.LocalDateTime;
13. @Entity
14. @Table(name = "comments")
15. @Data
16. @NoArgsConstructor
17. @AllArgsConstructor
18. public class Comment {
19.     @Id
20.     @GeneratedValue(strategy = GenerationType.IDENTITY)
21.     private Long id;
23.     @NotBlank
24.     @Size(min = 1, max = 1000)
25.     private String text;
27.     @Column(name = "created_at")
28.     private LocalDateTime createdAt;
30.     @Column(name = "updated_at")
31.     private LocalDateTime updatedAt;
33.     @ManyToOne(fetch = FetchType.LAZY)
34.     @JoinColumn(name = "post_id")
35.     private Post post;
37.     @ManyToOne(fetch = FetchType.LAZY)
38.     @JoinColumn(name = "author_id")
39.     private User author;
41.     public Comment(String text, Post post, User author) {
42.         this.text = text;
43.         this.post = post;
44.         this.author = author;
45.         this.createdAt = LocalDateTime.now();
46.         this.updatedAt = LocalDateTime.now();
47.     }
48. }

复制代码

DTO类

定义用户相关的DTO：

2. package com.example.blog.dto.request;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import javax.validation.constraints.Email;
9. import javax.validation.constraints.NotBlank;
10. import javax.validation.constraints.Size;
12. @ApiModel(description = "创建用户请求")
13. @Data
14. public class CreateUserRequest {
15.     @ApiModelProperty(value = "用户名", example = "john_doe", required = true, notes = "用户名必须是唯一的，只能包含字母、数字和下划线，长度在3到20个字符之间。")
16.     @NotBlank
17.     @Size(min = 3, max = 20)
18.     private String username;
20.     @ApiModelProperty(value = "电子邮箱", example = "john@example.com", required = true, notes = "必须是有效的电子邮件地址格式。")
21.     @NotBlank
22.     @Size(max = 50)
23.     @Email
24.     private String email;
26.     @ApiModelProperty(value = "密码", example = "password123", required = true, notes = "密码必须至少包含6个字符。")
27.     @NotBlank
28.     @Size(min = 6, max = 100)
29.     private String password;
30. }

复制代码

2. package com.example.blog.dto.response;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import java.time.LocalDateTime;
9. import java.util.Set;
11. @ApiModel(description = "用户响应")
12. @Data
13. public class UserResponse {
14.     @ApiModelProperty(value = "用户ID", example = "1", readOnly = true)
15.     private Long id;
17.     @ApiModelProperty(value = "用户名", example = "john_doe")
18.     private String username;
20.     @ApiModelProperty(value = "电子邮箱", example = "john@example.com")
21.     private String email;
23.     @ApiModelProperty(value = "创建时间", example = "2023-01-01T00:00:00", readOnly = true)
24.     private LocalDateTime createdAt;
26.     @ApiModelProperty(value = "更新时间", example = "2023-01-01T00:00:00", readOnly = true)
27.     private LocalDateTime updatedAt;
29.     @ApiModelProperty(value = "用户角色", example = "["ROLE_USER"]")
30.     private Set<String> roles;
31. }

复制代码

定义文章相关的DTO：

2. package com.example.blog.dto.request;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import javax.validation.constraints.NotBlank;
9. import javax.validation.constraints.Size;
11. @ApiModel(description = "创建文章请求")
12. @Data
13. public class CreatePostRequest {
14.     @ApiModelProperty(value = "文章标题", example = "如何使用Swagger创建API文档", required = true, notes = "标题长度在1到100个字符之间。")
15.     @NotBlank
16.     @Size(min = 1, max = 100)
17.     private String title;
19.     @ApiModelProperty(value = "文章内容", example = "Swagger是一个强大的API文档工具...", required = true, notes = "内容长度在1到5000个字符之间。")
20.     @NotBlank
21.     @Size(min = 1, max = 5000)
22.     private String content;
23. }

复制代码

2. package com.example.blog.dto.response;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import java.time.LocalDateTime;
10. @ApiModel(description = "文章响应")
11. @Data
12. public class PostResponse {
13.     @ApiModelProperty(value = "文章ID", example = "1", readOnly = true)
14.     private Long id;
16.     @ApiModelProperty(value = "文章标题", example = "如何使用Swagger创建API文档")
17.     private String title;
19.     @ApiModelProperty(value = "文章内容", example = "Swagger是一个强大的API文档工具...")
20.     private String content;
22.     @ApiModelProperty(value = "创建时间", example = "2023-01-01T00:00:00", readOnly = true)
23.     private LocalDateTime createdAt;
25.     @ApiModelProperty(value = "更新时间", example = "2023-01-01T00:00:00", readOnly = true)
26.     private LocalDateTime updatedAt;
28.     @ApiModelProperty(value = "作者信息", readOnly = true)
29.     private UserResponse author;
30. }

复制代码

定义评论相关的DTO：

2. package com.example.blog.dto.request;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import javax.validation.constraints.NotBlank;
9. import javax.validation.constraints.Size;
11. @ApiModel(description = "创建评论请求")
12. @Data
13. public class CreateCommentRequest {
14.     @ApiModelProperty(value = "评论内容", example = "这篇文章写得很好！", required = true, notes = "评论内容长度在1到1000个字符之间。")
15.     @NotBlank
16.     @Size(min = 1, max = 1000)
17.     private String text;
18. }

复制代码

2. package com.example.blog.dto.response;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import java.time.LocalDateTime;
10. @ApiModel(description = "评论响应")
11. @Data
12. public class CommentResponse {
13.     @ApiModelProperty(value = "评论ID", example = "1", readOnly = true)
14.     private Long id;
16.     @ApiModelProperty(value = "评论内容", example = "这篇文章写得很好！")
17.     private String text;
19.     @ApiModelProperty(value = "创建时间", example = "2023-01-01T00:00:00", readOnly = true)
20.     private LocalDateTime createdAt;
22.     @ApiModelProperty(value = "更新时间", example = "2023-01-01T00:00:00", readOnly = true)
23.     private LocalDateTime updatedAt;
25.     @ApiModelProperty(value = "作者信息", readOnly = true)
26.     private UserResponse author;
27. }

复制代码

定义登录请求DTO：

2. package com.example.blog.dto.request;
4. import io.swagger.annotations.ApiModel;
5. import io.swagger.annotations.ApiModelProperty;
6. import lombok.Data;
8. import javax.validation.constraints.NotBlank;
10. @ApiModel(description = "登录请求")
11. @Data
12. public class LoginRequest {
13.     @ApiModelProperty(value = "用户名或邮箱", example = "john_doe", required = true)
14.     @NotBlank
15.     private String usernameOrEmail;
17.     @ApiModelProperty(value = "密码", example = "password123", required = true)
18.     @NotBlank
19.     private String password;
20. }

复制代码

控制器类

定义认证控制器：

2. package com.example.blog.controller;
4. import com.example.blog.dto.request.LoginRequest;
5. import com.example.blog.security.JwtAuthenticationResponse;
6. import com.example.blog.security.JwtTokenProvider;
7. import io.swagger.annotations.Api;
8. import io.swagger.annotations.ApiOperation;
9. import io.swagger.annotations.ApiResponse;
10. import io.swagger.annotations.ApiResponses;
11. import org.springframework.beans.factory.annotation.Autowired;
12. import org.springframework.http.ResponseEntity;
13. import org.springframework.security.authentication.AuthenticationManager;
14. import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
15. import org.springframework.security.core.Authentication;
16. import org.springframework.security.core.context.SecurityContextHolder;
17. import org.springframework.web.bind.annotation.PostMapping;
18. import org.springframework.web.bind.annotation.RequestBody;
19. import org.springframework.web.bind.annotation.RequestMapping;
20. import org.springframework.web.bind.annotation.RestController;
22. import javax.validation.Valid;
24. @Api(tags = "认证管理")
25. @RestController
26. @RequestMapping("/api/auth")
27. public class AuthController {
29.     @Autowired
30.     private AuthenticationManager authenticationManager;
32.     @Autowired
33.     private JwtTokenProvider tokenProvider;
35.     @ApiOperation(value = "用户登录", notes = "使用用户名/邮箱和密码进行登录，成功后返回JWT令牌。")
36.     @ApiResponses(value = {
37.             @ApiResponse(code = 200, message = "登录成功", response = JwtAuthenticationResponse.class),
38.             @ApiResponse(code = 400, message = "无效的输入数据"),
39.             @ApiResponse(code = 401, message = "认证失败")
40.     })
41.     @PostMapping("/signin")
42.     public ResponseEntity<JwtAuthenticationResponse> authenticateUser(@Valid @RequestBody LoginRequest loginRequest) {
43.         Authentication authentication = authenticationManager.authenticate(
44.                 new UsernamePasswordAuthenticationToken(
45.                         loginRequest.getUsernameOrEmail(),
46.                         loginRequest.getPassword()
47.                 )
48.         );
50.         SecurityContextHolder.getContext().setAuthentication(authentication);
51.         String jwt = tokenProvider.generateToken(authentication);
52.         return ResponseEntity.ok(new JwtAuthenticationResponse(jwt));
53.     }
54. }

复制代码

定义用户控制器：

2. package com.example.blog.controller;
4. import com.example.blog.dto.request.CreateUserRequest;
5. import com.example.blog.dto.response.UserResponse;
6. import com.example.blog.model.User;
7. import com.example.blog.service.UserService;
8. import io.swagger.annotations.Api;
9. import io.swagger.annotations.ApiOperation;
10. import io.swagger.annotations.ApiParam;
11. import io.swagger.annotations.ApiResponse;
12. import io.swagger.annotations.ApiResponses;
13. import org.modelmapper.ModelMapper;
14. import org.springframework.beans.factory.annotation.Autowired;
15. import org.springframework.http.HttpStatus;
16. import org.springframework.http.ResponseEntity;
17. import org.springframework.security.access.prepost.PreAuthorize;
18. import org.springframework.web.bind.annotation.*;
20. import javax.validation.Valid;
21. import java.util.List;
22. import java.util.stream.Collectors;
24. @Api(tags = "用户管理")
25. @RestController
26. @RequestMapping("/api/users")
27. public class UserController {
29.     @Autowired
30.     private UserService userService;
32.     @Autowired
33.     private ModelMapper modelMapper;
35.     @ApiOperation(value = "创建新用户", notes = "创建一个新的用户账户。")
36.     @ApiResponses(value = {
37.             @ApiResponse(code = 201, message = "用户创建成功", response = UserResponse.class),
38.             @ApiResponse(code = 400, message = "无效的输入数据"),
39.             @ApiResponse(code = 409, message = "用户名或邮箱已存在")
40.     })
41.     @PostMapping
42.     public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest createUserRequest) {
43.         User user = modelMapper.map(createUserRequest, User.class);
44.         User createdUser = userService.createUser(user);
45.         UserResponse userResponse = modelMapper.map(createdUser, UserResponse.class);
46.         return new ResponseEntity<>(userResponse, HttpStatus.CREATED);
47.     }
49.     @ApiOperation(value = "获取所有用户", notes = "获取系统中所有用户的列表。需要管理员权限。")
50.     @ApiResponses(value = {
51.             @ApiResponse(code = 200, message = "成功获取用户列表", response = UserResponse.class, responseContainer = "List"),
52.             @ApiResponse(code = 403, message = "没有权限访问")
53.     })
54.     @PreAuthorize("hasRole('ADMIN')")
55.     @GetMapping
56.     public ResponseEntity<List<UserResponse>> getAllUsers() {
57.         List<User> users = userService.getAllUsers();
58.         List<UserResponse> userResponses = users.stream()
59.                 .map(user -> modelMapper.map(user, UserResponse.class))
60.                 .collect(Collectors.toList());
61.         return ResponseEntity.ok(userResponses);
62.     }
64.     @ApiOperation(value = "根据ID获取用户", notes = "根据用户ID获取用户信息。")
65.     @ApiResponses(value = {
66.             @ApiResponse(code = 200, message = "成功获取用户", response = UserResponse.class),
67.             @ApiResponse(code = 404, message = "用户不存在")
68.     })
69.     @GetMapping("/{id}")
70.     public ResponseEntity<UserResponse> getUserById(
71.             @ApiParam(value = "用户ID", example = "1", required = true) @PathVariable Long id) {
72.         User user = userService.getUserById(id);
73.         UserResponse userResponse = modelMapper.map(user, UserResponse.class);
74.         return ResponseEntity.ok(userResponse);
75.     }
76. }

复制代码

定义文章控制器：

2. package com.example.blog.controller;
4. import com.example.blog.dto.request.CreatePostRequest;
5. import com.example.blog.dto.response.PostResponse;
6. import com.example.blog.model.Post;
7. import com.example.blog.model.User;
8. import com.example.blog.service.PostService;
9. import com.example.blog.service.UserService;
10. import io.swagger.annotations.Api;
11. import io.swagger.annotations.ApiOperation;
12. import io.swagger.annotations.ApiParam;
13. import io.swagger.annotations.ApiResponse;
14. import io.swagger.annotations.ApiResponses;
15. import org.modelmapper.ModelMapper;
16. import org.springframework.beans.factory.annotation.Autowired;
17. import org.springframework.data.domain.Page;
18. import org.springframework.data.domain.Pageable;
19. import org.springframework.http.HttpStatus;
20. import org.springframework.http.ResponseEntity;
21. import org.springframework.security.core.Authentication;
22. import org.springframework.web.bind.annotation.*;
24. import javax.validation.Valid;
25. import java.util.List;
26. import java.util.stream.Collectors;
28. @Api(tags = "文章管理")
29. @RestController
30. @RequestMapping("/api/posts")
31. public class PostController {
33.     @Autowired
34.     private PostService postService;
36.     @Autowired
37.     private UserService userService;
39.     @Autowired
40.     private ModelMapper modelMapper;
42.     @ApiOperation(value = "创建新文章", notes = "创建一篇新的文章。需要用户登录。")
43.     @ApiResponses(value = {
44.             @ApiResponse(code = 201, message = "文章创建成功", response = PostResponse.class),
45.             @ApiResponse(code = 400, message = "无效的输入数据"),
46.             @ApiResponse(code = 401, message = "未登录")
47.     })
48.     @PostMapping
49.     public ResponseEntity<PostResponse> createPost(
50.             @Valid @RequestBody CreatePostRequest createPostRequest,
51.             Authentication authentication) {
52.         User author = userService.getUserByUsername(authentication.getName());
53.         Post post = modelMapper.map(createPostRequest, Post.class);
54.         post.setAuthor(author);
55.         Post createdPost = postService.createPost(post);
56.         PostResponse postResponse = modelMapper.map(createdPost, PostResponse.class);
57.         return new ResponseEntity<>(postResponse, HttpStatus.CREATED);
58.     }
60.     @ApiOperation(value = "获取所有文章", notes = "获取系统中所有文章的列表，支持分页。")
61.     @ApiResponses(value = {
62.             @ApiResponse(code = 200, message = "成功获取文章列表", response = PostResponse.class, responseContainer = "Page")
63.     })
64.     @GetMapping
65.     public ResponseEntity<Page<PostResponse>> getAllPosts(Pageable pageable) {
66.         Page<Post> posts = postService.getAllPosts(pageable);
67.         Page<PostResponse> postResponses = posts.map(post -> modelMapper.map(post, PostResponse.class));
68.         return ResponseEntity.ok(postResponses);
69.     }
71.     @ApiOperation(value = "根据ID获取文章", notes = "根据文章ID获取文章信息。")
72.     @ApiResponses(value = {
73.             @ApiResponse(code = 200, message = "成功获取文章", response = PostResponse.class),
74.             @ApiResponse(code = 404, message = "文章不存在")
75.     })
76.     @GetMapping("/{id}")
77.     public ResponseEntity<PostResponse> getPostById(
78.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long id) {
79.         Post post = postService.getPostById(id);
80.         PostResponse postResponse = modelMapper.map(post, PostResponse.class);
81.         return ResponseEntity.ok(postResponse);
82.     }
84.     @ApiOperation(value = "更新文章", notes = "更新指定的文章。只有文章作者或管理员可以更新文章。")
85.     @ApiResponses(value = {
86.             @ApiResponse(code = 200, message = "文章更新成功", response = PostResponse.class),
87.             @ApiResponse(code = 400, message = "无效的输入数据"),
88.             @ApiResponse(code = 401, message = "未登录"),
89.             @ApiResponse(code = 403, message = "没有权限更新此文章"),
90.             @ApiResponse(code = 404, message = "文章不存在")
91.     })
92.     @PutMapping("/{id}")
93.     public ResponseEntity<PostResponse> updatePost(
94.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long id,
95.             @Valid @RequestBody CreatePostRequest createPostRequest,
96.             Authentication authentication) {
97.         User currentUser = userService.getUserByUsername(authentication.getName());
98.         Post existingPost = postService.getPostById(id);
99.         
100.         // 检查用户是否有权限更新文章
101.         if (!existingPost.getAuthor().getId().equals(currentUser.getId()) &&
102.             !currentUser.getRoles().contains(User.Role.ROLE_ADMIN)) {
103.             return new ResponseEntity<>(HttpStatus.FORBIDDEN);
104.         }
105.         
106.         Post post = modelMapper.map(createPostRequest, Post.class);
107.         post.setId(id);
108.         post.setAuthor(existingPost.getAuthor());
109.         post.setCreatedAt(existingPost.getCreatedAt());
110.         Post updatedPost = postService.updatePost(post);
111.         PostResponse postResponse = modelMapper.map(updatedPost, PostResponse.class);
112.         return ResponseEntity.ok(postResponse);
113.     }
115.     @ApiOperation(value = "删除文章", notes = "删除指定的文章。只有文章作者或管理员可以删除文章。")
116.     @ApiResponses(value = {
117.             @ApiResponse(code = 204, message = "文章删除成功"),
118.             @ApiResponse(code = 401, message = "未登录"),
119.             @ApiResponse(code = 403, message = "没有权限删除此文章"),
120.             @ApiResponse(code = 404, message = "文章不存在")
121.     })
122.     @DeleteMapping("/{id}")
123.     public ResponseEntity<Void> deletePost(
124.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long id,
125.             Authentication authentication) {
126.         User currentUser = userService.getUserByUsername(authentication.getName());
127.         Post post = postService.getPostById(id);
128.         
129.         // 检查用户是否有权限删除文章
130.         if (!post.getAuthor().getId().equals(currentUser.getId()) &&
131.             !currentUser.getRoles().contains(User.Role.ROLE_ADMIN)) {
132.             return new ResponseEntity<>(HttpStatus.FORBIDDEN);
133.         }
134.         
135.         postService.deletePost(id);
136.         return new ResponseEntity<>(HttpStatus.NO_CONTENT);
137.     }
138. }

复制代码

定义评论控制器：

2. package com.example.blog.controller;
4. import com.example.blog.dto.request.CreateCommentRequest;
5. import com.example.blog.dto.response.CommentResponse;
6. import com.example.blog.model.Comment;
7. import com.example.blog.model.Post;
8. import com.example.blog.model.User;
9. import com.example.blog.service.CommentService;
10. import com.example.blog.service.PostService;
11. import com.example.blog.service.UserService;
12. import io.swagger.annotations.Api;
13. import io.swagger.annotations.ApiOperation;
14. import io.swagger.annotations.ApiParam;
15. import io.swagger.annotations.ApiResponse;
16. import io.swagger.annotations.ApiResponses;
17. import org.modelmapper.ModelMapper;
18. import org.springframework.beans.factory.annotation.Autowired;
19. import org.springframework.http.HttpStatus;
20. import org.springframework.http.ResponseEntity;
21. import org.springframework.security.core.Authentication;
22. import org.springframework.web.bind.annotation.*;
24. import javax.validation.Valid;
25. import java.util.List;
26. import java.util.stream.Collectors;
28. @Api(tags = "评论管理")
29. @RestController
30. @RequestMapping("/api/posts/{postId}/comments")
31. public class CommentController {
33.     @Autowired
34.     private CommentService commentService;
36.     @Autowired
37.     private PostService postService;
39.     @Autowired
40.     private UserService userService;
42.     @Autowired
43.     private ModelMapper modelMapper;
45.     @ApiOperation(value = "创建新评论", notes = "为指定文章创建一条新评论。需要用户登录。")
46.     @ApiResponses(value = {
47.             @ApiResponse(code = 201, message = "评论创建成功", response = CommentResponse.class),
48.             @ApiResponse(code = 400, message = "无效的输入数据"),
49.             @ApiResponse(code = 401, message = "未登录"),
50.             @ApiResponse(code = 404, message = "文章不存在")
51.     })
52.     @PostMapping
53.     public ResponseEntity<CommentResponse> createComment(
54.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long postId,
55.             @Valid @RequestBody CreateCommentRequest createCommentRequest,
56.             Authentication authentication) {
57.         Post post = postService.getPostById(postId);
58.         User author = userService.getUserByUsername(authentication.getName());
59.         Comment comment = modelMapper.map(createCommentRequest, Comment.class);
60.         comment.setPost(post);
61.         comment.setAuthor(author);
62.         Comment createdComment = commentService.createComment(comment);
63.         CommentResponse commentResponse = modelMapper.map(createdComment, CommentResponse.class);
64.         return new ResponseEntity<>(commentResponse, HttpStatus.CREATED);
65.     }
67.     @ApiOperation(value = "获取文章的所有评论", notes = "获取指定文章的所有评论列表。")
68.     @ApiResponses(value = {
69.             @ApiResponse(code = 200, message = "成功获取评论列表", response = CommentResponse.class, responseContainer = "List"),
70.             @ApiResponse(code = 404, message = "文章不存在")
71.     })
72.     @GetMapping
73.     public ResponseEntity<List<CommentResponse>> getCommentsByPostId(
74.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long postId) {
75.         Post post = postService.getPostById(postId);
76.         List<Comment> comments = commentService.getCommentsByPostId(postId);
77.         List<CommentResponse> commentResponses = comments.stream()
78.                 .map(comment -> modelMapper.map(comment, CommentResponse.class))
79.                 .collect(Collectors.toList());
80.         return ResponseEntity.ok(commentResponses);
81.     }
83.     @ApiOperation(value = "删除评论", notes = "删除指定的评论。只有评论作者、文章作者或管理员可以删除评论。")
84.     @ApiResponses(value = {
85.             @ApiResponse(code = 204, message = "评论删除成功"),
86.             @ApiResponse(code = 401, message = "未登录"),
87.             @ApiResponse(code = 403, message = "没有权限删除此评论"),
88.             @ApiResponse(code = 404, message = "评论不存在")
89.     })
90.     @DeleteMapping("/{commentId}")
91.     public ResponseEntity<Void> deleteComment(
92.             @ApiParam(value = "文章ID", example = "1", required = true) @PathVariable Long postId,
93.             @ApiParam(value = "评论ID", example = "1", required = true) @PathVariable Long commentId,
94.             Authentication authentication) {
95.         User currentUser = userService.getUserByUsername(authentication.getName());
96.         Comment comment = commentService.getCommentById(commentId);
97.         
98.         // 检查用户是否有权限删除评论
99.         if (!comment.getAuthor().getId().equals(currentUser.getId()) &&
100.             !comment.getPost().getAuthor().getId().equals(currentUser.getId()) &&
101.             !currentUser.getRoles().contains(User.Role.ROLE_ADMIN)) {
102.             return new ResponseEntity<>(HttpStatus.FORBIDDEN);
103.         }
104.         
105.         commentService.deleteComment(commentId);
106.         return new ResponseEntity<>(HttpStatus.NO_CONTENT);
107.     }
108. }

复制代码

运行和测试

启动应用程序后，访问以下URL查看Swagger UI：

2. http://localhost:8080/swagger-ui.html

复制代码

您将看到一个专业、易读的API文档，包括：

1. 认证管理
2. 用户管理
3. 文章管理
4. 评论管理

每个API都有详细的描述、参数说明、请求示例和响应示例。您可以直接在Swagger UI中测试API，只需点击”Try it out”按钮，填入参数，然后点击”Execute”。

效果展示

通过以上配置，我们实现了一个功能完整、文档完善的博客系统API。Swagger UI将显示：

1. 清晰的API分组：按照功能模块将API分为认证管理、用户管理、文章管理和评论管理四个部分。
2. 详细的API描述：每个API都有清晰的功能描述和使用说明。
3. 完整的参数说明：包括参数类型、是否必需、示例值等。
4. 丰富的请求示例：为每个API提供了符合规范的请求示例。
5. 详细的响应说明：包括不同HTTP状态码的含义和对应的响应结构。
6. 认证集成：支持JWT认证，可以在Swagger UI中直接输入令牌进行测试。

这样的API文档不仅对前端开发者友好，也便于后端开发者进行测试和维护，大大提高了开发效率。

总结

本文详细介绍了如何使用Swagger配置请求示例，打造专业、易读的API文档，从而提升开发效率。我们从Swagger的基础概念入手，逐步深入到环境搭建、基础配置、注解详解、请求示例配置、高级功能、最佳实践和实战案例，全面覆盖了Swagger的使用技巧。

通过本文的学习，您应该能够：

1. 在项目中集成Swagger并配置基本参数。
2. 使用Swagger注解丰富API文档的内容。
3. 添加请求和响应示例，提高API文档的实用性。
4. 利用Swagger的高级功能，如API分组、自定义UI等。
5. 遵循最佳实践，创建高质量的API文档。
6. 通过实战案例，掌握Swagger在实际项目中的应用。

Swagger作为一款强大的API文档工具，不仅能够自动生成文档，还能提供交互式的API测试功能，大大简化了API开发和测试的流程。通过合理使用Swagger，您可以创建专业、易读的API文档，提高团队协作效率，加速项目开发进程。

随着API经济的不断发展，API文档的重要性将日益凸显。掌握Swagger等API文档工具，将成为现代软件开发者的必备技能。希望本文能够帮助您更好地使用Swagger，打造出高质量的API文档，提升开发效率和用户体验。