活动公告

系统通知
通知：关于部分勋章领取条件及购买价格调整的通知
05-18 21:22
系统通知
通知：本站资源由网友上传分享，如有违规等问题请到版务模块进行投诉，资源失效请在帖子内回复要求补档，会尽快处理！
10-23 09:31
>社区 > 科技 > 经验交流 >帖子
本版发帖返回

Swagger2.0与Spring Boot 2.0完美整合 从零开始构建现代化API文档管理系统 提升开发效率与团队协作能力 快速实现接口自动化测试

这是个蓝孩子 当前离线 威震华夏关云长
SunJu_FaceMall

3万

主题

2860

科技点

3万

积分

白金月票

碾压王

积分
32872

塔罗立华奏
<font color=白金月票" /> 发表于 2025-9-9 19:30:13 | 显示全部楼层 |阅读模式

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要 登录 才可以下载或查看，没有账号？立即注册

x
引言

在当今快速发展的软件开发领域，API（应用程序编程接口）已经成为不同系统之间通信的核心。随着微服务架构的普及，API的数量和复杂性也在不断增加，这使得API文档的管理和维护变得尤为重要。良好的API文档不仅可以帮助开发者理解和使用API，还能促进团队成员之间的协作，提高开发效率。

Swagger（现称为OpenAPI Specification）是一个强大且广泛使用的API文档规范和工具集，它可以帮助我们设计、构建、记录和使用RESTful Web服务。而Spring Boot作为Java生态系统中最受欢迎的框架之一，简化了Spring应用程序的创建和部署过程。

本文将详细介绍如何将Swagger2.0与Spring Boot 2.0完美整合，从零开始构建一个现代化的API文档管理系统，从而提升开发效率与团队协作能力，并快速实现接口自动化测试。

Swagger2.0简介

Swagger2.0是一个用于描述和记录RESTful API的规范和工具集。它允许开发者以一种标准化的方式定义API的结构，包括端点、参数、请求/响应模型等。Swagger2.0的核心组件包括：

1. Swagger Specification：一个JSON或YAML格式的API描述文件，定义了API的结构和行为。
2. Swagger UI：一个基于HTML的交互式API文档界面，允许开发者查看和测试API。
3. Swagger Editor：一个在线编辑器，用于编写和验证Swagger规范。
4. Swagger Codegen：一个代码生成工具，可以根据Swagger规范生成客户端SDK和服务器存根。

Swagger2.0的主要优势包括：

• 交互式API文档：提供可视化的API文档，开发者可以直接在浏览器中测试API端点。
• 标准化API描述：使用统一的格式描述API，便于理解和维护。
• 客户端代码生成：可以根据API描述自动生成客户端代码，减少重复工作。
• 自动化测试：结合其他工具，可以实现API的自动化测试。
• 团队协作：提供统一的API文档平台，促进团队成员之间的协作。

Spring Boot 2.0简介

Spring Boot 2.0是Spring框架的一个版本，它简化了Spring应用程序的创建和部署过程。Spring Boot 2.0引入了许多新特性和改进，包括：

1. 自动配置：根据项目依赖自动配置Spring应用程序，减少手动配置的需要。
2. 嵌入式服务器：内置Tomcat、Jetty或Undertow服务器，无需单独部署WAR文件。
3. 生产就绪特性：提供健康检查、指标收集和外部化配置等生产环境所需的功能。
4. Spring 5框架支持：基于Spring 5框架构建，支持响应式编程模型。
5. 改进的性能和内存使用：优化了性能和内存使用，适合构建微服务架构。
6. 对Java 9的支持：完全支持Java 9的新特性。

Spring Boot 2.0的主要优势包括：

• 简化开发：减少样板代码和配置，让开发者专注于业务逻辑。
• 快速启动：项目可以快速启动和运行，提高开发效率。
• 微服务友好：非常适合构建和部署微服务架构。
• 丰富的生态系统：与Spring生态系统中的其他项目无缝集成。
• 社区支持：拥有庞大的开发者社区和丰富的学习资源。

环境准备

在开始整合Swagger2.0和Spring Boot 2.0之前，我们需要准备开发环境。以下是所需的环境和工具：

1. Java Development Kit (JDK)：安装JDK 8或更高版本。建议使用JDK 11，因为它是Spring Boot 2.0的长期支持版本。
  2. # 检查Java版本
  3.    java -version
复制代码

1. 集成开发环境 (IDE)：推荐使用IntelliJ IDEA或Eclipse。这些IDE提供了强大的Spring Boot支持，可以简化开发过程。
2. 构建工具：Maven或Gradle。本文将使用Maven作为构建工具。
3. Spring Boot CLI（可选）：可以用于快速创建和测试Spring Boot应用程序。
4. Postman（可选）：用于测试API端点。
5. Git：用于版本控制。

集成开发环境 (IDE)：推荐使用IntelliJ IDEA或Eclipse。这些IDE提供了强大的Spring Boot支持，可以简化开发过程。

构建工具：Maven或Gradle。本文将使用Maven作为构建工具。

Spring Boot CLI（可选）：可以用于快速创建和测试Spring Boot应用程序。

Postman（可选）：用于测试API端点。

Git：用于版本控制。

创建一个新的Spring Boot项目可以通过以下几种方式：

使用Spring Initializr网站

1. 访问https://start.spring.io/
2. 选择以下配置：Project: Maven ProjectLanguage: JavaSpring Boot: 2.7.x（或更高版本）Project Metadata:Group: com.exampleArtifact: swagger-spring-boot-demoName: swagger-spring-boot-demoDescription: Demo project for Spring Boot with SwaggerPackage Name: com.example.swaggerspringbootdemoDependencies: Spring Web
3. Project: Maven Project
4. Language: Java
5. Spring Boot: 2.7.x（或更高版本）
6. Project Metadata:Group: com.exampleArtifact: swagger-spring-boot-demoName: swagger-spring-boot-demoDescription: Demo project for Spring Boot with SwaggerPackage Name: com.example.swaggerspringbootdemo
7. Group: com.example
8. Artifact: swagger-spring-boot-demo
9. Name: swagger-spring-boot-demo
10. Description: Demo project for Spring Boot with Swagger
11. Package Name: com.example.swaggerspringbootdemo
12. Dependencies: Spring Web
13. 点击”Generate”按钮下载项目压缩包。
14. 解压压缩包，并在IDE中打开项目。

访问https://start.spring.io/

选择以下配置：

• Project: Maven Project
• Language: Java
• Spring Boot: 2.7.x（或更高版本）
• Project Metadata:Group: com.exampleArtifact: swagger-spring-boot-demoName: swagger-spring-boot-demoDescription: Demo project for Spring Boot with SwaggerPackage Name: com.example.swaggerspringbootdemo
• Group: com.example
• Artifact: swagger-spring-boot-demo
• Name: swagger-spring-boot-demo
• Description: Demo project for Spring Boot with Swagger
• Package Name: com.example.swaggerspringbootdemo
• Dependencies: Spring Web

• Group: com.example
• Artifact: swagger-spring-boot-demo
• Name: swagger-spring-boot-demo
• Description: Demo project for Spring Boot with Swagger
• Package Name: com.example.swaggerspringbootdemo

点击”Generate”按钮下载项目压缩包。

解压压缩包，并在IDE中打开项目。

使用Spring Boot CLI
  2. # 使用Spring Boot CLI创建项目
  3. spring init --dependencies=web swagger-spring-boot-demo
  4. cd swagger-spring-boot-demo
复制代码

整合步骤

现在，我们开始将Swagger2.0与Spring Boot 2.0整合。以下是详细的步骤和代码示例：

添加Swagger依赖

首先，我们需要在项目的pom.xml文件中添加Swagger2.0的依赖：
  2. <dependencies>
  3.     <!-- Spring Boot Web Starter -->
  4.     <dependency>
  5.         <groupId>org.springframework.boot</groupId>
  6.         <artifactId>spring-boot-starter-web</artifactId>
  7.     </dependency>
  8.    
  9.     <!-- Swagger2 -->
  10.     <dependency>
  11.         <groupId>io.springfox</groupId>
  12.         <artifactId>springfox-swagger2</artifactId>
  13.         <version>2.9.2</version>
  14.     </dependency>
  15.    
  16.     <!-- Swagger UI -->
  17.     <dependency>
  18.         <groupId>io.springfox</groupId>
  19.         <artifactId>springfox-swagger-ui</artifactId>
  20.         <version>2.9.2</version>
  21.     </dependency>
  22.    
  23.     <!-- Spring Boot Test -->
  24.     <dependency>
  25.         <groupId>org.springframework.boot</groupId>
  26.         <artifactId>spring-boot-starter-test</artifactId>
  27.         <scope>test</scope>
  28.     </dependency>
  29. </dependencies>
复制代码

在这里，我们添加了两个主要的Swagger依赖：

• springfox-swagger2：提供Swagger2的核心功能。
• springfox-swagger-ui：提供Swagger UI界面。

配置Swagger

接下来，我们需要创建一个配置类来启用Swagger：
  2. package com.example.swaggerspringbootdemo.config;
  4. import org.springframework.context.annotation.Bean;
  5. import org.springframework.context.annotation.Configuration;
  6. import springfox.documentation.builders.ApiInfoBuilder;
  7. import springfox.documentation.builders.PathSelectors;
  8. import springfox.documentation.builders.RequestHandlerSelectors;
  9. import springfox.documentation.service.ApiInfo;
  10. import springfox.documentation.service.Contact;
  11. import springfox.documentation.spi.DocumentationType;
  12. import springfox.documentation.spring.web.plugins.Docket;
  13. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  15. @Configuration
  16. @EnableSwagger2
  17. public class SwaggerConfig {
  19.     @Bean
  20.     public Docket api() {
  21.         return new Docket(DocumentationType.SWAGGER_2)
  22.                 .select()
  23.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller"))
  24.                 .paths(PathSelectors.any())
  25.                 .build()
  26.                 .apiInfo(apiInfo());
  27.     }
  29.     private ApiInfo apiInfo() {
  30.         return new ApiInfoBuilder()
  31.                 .title("Spring Boot REST API with Swagger")
  32.                 .description("Spring Boot REST API with Swagger documentation")
  33.                 .version("1.0")
  34.                 .contact(new Contact("John Doe", "https://example.com", "john.doe@example.com"))
  35.                 .build();
  36.     }
  37. }
复制代码

在这个配置类中：

• @Configuration注解表示这是一个配置类。
• @EnableSwagger2注解启用Swagger2。
• DocketBean是Swagger的主要配置类，它定义了API文档的生成方式。
• apis()方法指定要扫描的控制器包。
• paths()方法指定要包含的路径模式。
• apiInfo()方法设置API的基本信息，如标题、描述和版本。

创建API控制器

现在，让我们创建一个简单的REST控制器，并使用Swagger注解来描述API：
  2. package com.example.swaggerspringbootdemo.controller;
  4. import io.swagger.annotations.Api;
  5. import io.swagger.annotations.ApiOperation;
  6. import io.swagger.annotations.ApiParam;
  7. import io.swagger.annotations.ApiResponse;
  8. import io.swagger.annotations.ApiResponses;
  9. import org.springframework.http.HttpStatus;
  10. import org.springframework.http.ResponseEntity;
  11. import org.springframework.web.bind.annotation.*;
  13. import java.util.ArrayList;
  14. import java.util.List;
  15. import java.util.concurrent.ConcurrentHashMap;
  16. import java.util.concurrent.atomic.AtomicLong;
  18. @Api(value = "User Management System", description = "Operations pertaining to user in User Management System")
  19. @RestController
  20. @RequestMapping("/api/users")
  21. public class UserController {
  23.     private final ConcurrentHashMap<Long, User> userMap = new ConcurrentHashMap<>();
  24.     private final AtomicLong counter = new AtomicLong(1);
  26.     @ApiOperation(value = "View a list of available users", response = List.class)
  27.     @ApiResponses(value = {
  28.             @ApiResponse(code = 200, message = "Successfully retrieved list"),
  29.             @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
  30.             @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
  31.             @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
  32.     })
  33.     @GetMapping
  34.     public ResponseEntity<List<User>> getAllUsers() {
  35.         return new ResponseEntity<>(new ArrayList<>(userMap.values()), HttpStatus.OK);
  36.     }
  38.     @ApiOperation(value = "Get a user by Id", response = User.class)
  39.     @GetMapping("/{id}")
  40.     public ResponseEntity<User> getUserById(
  41.             @ApiParam(value = "User id from which user object will retrieve", required = true) @PathVariable Long id) {
  42.         User user = userMap.get(id);
  43.         if (user == null) {
  44.             return new ResponseEntity<>(HttpStatus.NOT_FOUND);
  45.         }
  46.         return new ResponseEntity<>(user, HttpStatus.OK);
  47.     }
  49.     @ApiOperation(value = "Add a user")
  50.     @PostMapping
  51.     public ResponseEntity<User> createUser(
  52.             @ApiParam(value = "User object store in database table", required = true) @RequestBody User user) {
  53.         long id = counter.getAndIncrement();
  54.         user.setId(id);
  55.         userMap.put(id, user);
  56.         return new ResponseEntity<>(user, HttpStatus.CREATED);
  57.     }
  59.     @ApiOperation(value = "Update a user")
  60.     @PutMapping("/{id}")
  61.     public ResponseEntity<User> updateUser(
  62.             @ApiParam(value = "User Id to update user object", required = true) @PathVariable Long id,
  63.             @ApiParam(value = "Update user object", required = true) @RequestBody User user) {
  64.         if (!userMap.containsKey(id)) {
  65.             return new ResponseEntity<>(HttpStatus.NOT_FOUND);
  66.         }
  67.         user.setId(id);
  68.         userMap.put(id, user);
  69.         return new ResponseEntity<>(user, HttpStatus.OK);
  70.     }
  72.     @ApiOperation(value = "Delete a user")
  73.     @DeleteMapping("/{id}")
  74.     public ResponseEntity<Void> deleteUser(
  75.             @ApiParam(value = "User Id from which user object will delete from database table", required = true) @PathVariable Long id) {
  76.         if (!userMap.containsKey(id)) {
  77.             return new ResponseEntity<>(HttpStatus.NOT_FOUND);
  78.         }
  79.         userMap.remove(id);
  80.         return new ResponseEntity<>(HttpStatus.NO_CONTENT);
  81.     }
  82. }
复制代码

在这个控制器中，我们使用了多个Swagger注解：

• @Api：用于描述控制器类。
• @ApiOperation：用于描述方法的功能。
• @ApiParam：用于描述参数。
• @ApiResponses和@ApiResponse：用于描述可能的响应。

创建模型类

接下来，创建一个User模型类：
  2. package com.example.swaggerspringbootdemo.controller;
  4. import io.swagger.annotations.ApiModel;
  5. import io.swagger.annotations.ApiModelProperty;
  7. @ApiModel(description = "User details")
  8. public class User {
  9.     @ApiModelProperty(notes = "The database generated user ID")
  10.     private Long id;
  11.    
  12.     @ApiModelProperty(notes = "The user's first name", required = true)
  13.     private String firstName;
  14.    
  15.     @ApiModelProperty(notes = "The user's last name", required = true)
  16.     private String lastName;
  17.    
  18.     @ApiModelProperty(notes = "The user's email address", required = true)
  19.     private String email;
  21.     // Constructors, getters, and setters
  22.     public User() {
  23.     }
  25.     public User(String firstName, String lastName, String email) {
  26.         this.firstName = firstName;
  27.         this.lastName = lastName;
  28.         this.email = email;
  29.     }
  31.     public Long getId() {
  32.         return id;
  33.     }
  35.     public void setId(Long id) {
  36.         this.id = id;
  37.     }
  39.     public String getFirstName() {
  40.         return firstName;
  41.     }
  43.     public void setFirstName(String firstName) {
  44.         this.firstName = firstName;
  45.     }
  47.     public String getLastName() {
  48.         return lastName;
  49.     }
  51.     public void setLastName(String lastName) {
  52.         this.lastName = lastName;
  53.     }
  55.     public String getEmail() {
  56.         return email;
  57.     }
  59.     public void setEmail(String email) {
  60.         this.email = email;
  61.     }
  62. }
复制代码

在这个模型类中，我们使用了以下Swagger注解：

• @ApiModel：用于描述模型类。
• @ApiModelProperty：用于描述模型属性。

运行应用程序

现在，我们可以运行Spring Boot应用程序：
  2. package com.example.swaggerspringbootdemo;
  4. import org.springframework.boot.SpringApplication;
  5. import org.springframework.boot.autoconfigure.SpringBootApplication;
  7. @SpringBootApplication
  8. public class SwaggerSpringBootDemoApplication {
  10.     public static void main(String[] args) {
  11.         SpringApplication.run(SwaggerSpringBootDemoApplication.class, args);
  12.     }
  13. }
复制代码

启动应用程序后，访问http://localhost:8080/swagger-ui.html即可看到Swagger UI界面。在这个界面中，你可以查看所有API端点的文档，并进行测试。

高级功能

分组API

在大型项目中，我们可能需要对API进行分组，以便更好地组织和管理。Swagger支持通过多个Docket Bean来实现API分组：
  2. package com.example.swaggerspringbootdemo.config;
  4. import org.springframework.context.annotation.Bean;
  5. import org.springframework.context.annotation.Configuration;
  6. import springfox.documentation.builders.ApiInfoBuilder;
  7. import springfox.documentation.builders.PathSelectors;
  8. import springfox.documentation.builders.RequestHandlerSelectors;
  9. import springfox.documentation.service.ApiInfo;
  10. import springfox.documentation.service.Contact;
  11. import springfox.documentation.spi.DocumentationType;
  12. import springfox.documentation.spring.web.plugins.Docket;
  13. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  15. @Configuration
  16. @EnableSwagger2
  17. public class SwaggerConfig {
  19.     @Bean
  20.     public Docket publicApi() {
  21.         return new Docket(DocumentationType.SWAGGER_2)
  22.                 .groupName("public")
  23.                 .select()
  24.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller.public"))
  25.                 .paths(PathSelectors.any())
  26.                 .build()
  27.                 .apiInfo(publicApiInfo());
  28.     }
  30.     @Bean
  31.     public Docket privateApi() {
  32.         return new Docket(DocumentationType.SWAGGER_2)
  33.                 .groupName("private")
  34.                 .select()
  35.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller.private"))
  36.                 .paths(PathSelectors.any())
  37.                 .build()
  38.                 .apiInfo(privateApiInfo());
  39.     }
  41.     private ApiInfo publicApiInfo() {
  42.         return new ApiInfoBuilder()
  43.                 .title("Public API Documentation")
  44.                 .description("This is the documentation for public APIs")
  45.                 .version("1.0")
  46.                 .contact(new Contact("John Doe", "https://example.com", "john.doe@example.com"))
  47.                 .build();
  48.     }
  50.     private ApiInfo privateApiInfo() {
  51.         return new ApiInfoBuilder()
  52.                 .title("Private API Documentation")
  53.                 .description("This is the documentation for private APIs")
  54.                 .version("1.0")
  55.                 .contact(new Contact("John Doe", "https://example.com", "john.doe@example.com"))
  56.                 .build();
  57.     }
  58. }
复制代码

在这个配置中，我们创建了两个Docket Bean，分别对应公共API和私有API。每个Docket Bean都有自己的groupName，用于区分不同的API组。

自定义Swagger UI

Swagger UI可以通过自定义配置来满足不同的需求。我们可以创建一个自定义的Swagger UI配置：
  2. package com.example.swaggerspringbootdemo.config;
  4. import org.springframework.context.annotation.Configuration;
  5. import springfox.documentation.swagger.web.UiConfiguration;
  6. import springfox.documentation.swagger.web.UiConfigurationBuilder;
  8. @Configuration
  9. public class SwaggerUiConfig {
  11.     @Bean
  12.     public UiConfiguration uiConfiguration() {
  13.         return UiConfigurationBuilder.builder()
  14.                 .displayRequestDuration(true)
  15.                 .docExpansion("none")
  16.                 .filter(true)
  17.                 .showExtensions(true)
  18.                 .build();
  19.     }
  20. }
复制代码

在这个配置中，我们：

• 启用了请求持续时间显示。
• 设置了文档展开方式为”none”。
• 启用了过滤器。
• 启用了扩展显示。

安全配置

在实际应用中，我们可能需要保护API文档，只允许授权用户访问。我们可以通过Spring Security来实现：

首先，添加Spring Security依赖：
  2. <dependency>
  3.     <groupId>org.springframework.boot</groupId>
  4.     <artifactId>spring-boot-starter-security</artifactId>
  5. </dependency>
复制代码

然后，创建安全配置：
  2. package com.example.swaggerspringbootdemo.config;
  4. import org.springframework.context.annotation.Configuration;
  5. import org.springframework.security.config.annotation.web.builders.HttpSecurity;
  6. import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
  7. import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
  9. @Configuration
  10. @EnableWebSecurity
  11. public class SecurityConfig extends WebSecurityConfigurerAdapter {
  13.     @Override
  14.     protected void configure(HttpSecurity http) throws Exception {
  15.         http
  16.             .authorizeRequests()
  17.                 .antMatchers("/swagger-ui.html").authenticated()
  18.                 .antMatchers("/swagger-resources/**").authenticated()
  19.                 .antMatchers("/v2/api-docs").authenticated()
  20.                 .antMatchers("/webjars/**").authenticated()
  21.                 .anyRequest().permitAll()
  22.             .and()
  23.             .formLogin()
  24.             .and()
  25.             .httpBasic();
  26.     }
  27. }
复制代码

在这个配置中，我们要求访问Swagger UI和相关资源时必须进行身份验证，而其他API端点则允许所有人访问。

全局参数配置

在某些情况下，我们可能需要为所有API添加一些全局参数，例如认证令牌。这可以通过Docket配置来实现：
  2. package com.example.swaggerspringbootdemo.config;
  4. import org.springframework.context.annotation.Bean;
  5. import org.springframework.context.annotation.Configuration;
  6. import springfox.documentation.builders.ApiInfoBuilder;
  7. import springfox.documentation.builders.ParameterBuilder;
  8. import springfox.documentation.builders.PathSelectors;
  9. import springfox.documentation.builders.RequestHandlerSelectors;
  10. import springfox.documentation.schema.ModelRef;
  11. import springfox.documentation.service.ApiInfo;
  12. import springfox.documentation.service.Contact;
  13. import springfox.documentation.service.Parameter;
  14. import springfox.documentation.spi.DocumentationType;
  15. import springfox.documentation.spring.web.plugins.Docket;
  16. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  18. import java.util.ArrayList;
  19. import java.util.List;
  21. @Configuration
  22. @EnableSwagger2
  23. public class SwaggerConfig {
  25.     @Bean
  26.     public Docket api() {
  27.         // 添加全局参数
  28.         ParameterBuilder parameterBuilder = new ParameterBuilder();
  29.         List<Parameter> parameters = new ArrayList<>();
  30.         parameterBuilder.name("Authorization")
  31.                 .description("Authorization token")
  32.                 .modelRef(new ModelRef("string"))
  33.                 .parameterType("header")
  34.                 .required(false)
  35.                 .build();
  36.         parameters.add(parameterBuilder.build());
  38.         return new Docket(DocumentationType.SWAGGER_2)
  39.                 .select()
  40.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller"))
  41.                 .paths(PathSelectors.any())
  42.                 .build()
  43.                 .globalOperationParameters(parameters)
  44.                 .apiInfo(apiInfo());
  45.     }
  47.     private ApiInfo apiInfo() {
  48.         return new ApiInfoBuilder()
  49.                 .title("Spring Boot REST API with Swagger")
  50.                 .description("Spring Boot REST API with Swagger documentation")
  51.                 .version("1.0")
  52.                 .contact(new Contact("John Doe", "https://example.com", "john.doe@example.com"))
  53.                 .build();
  54.     }
  55. }
复制代码

在这个配置中，我们添加了一个名为”Authorization”的全局参数，它将出现在所有API端点中。

接口自动化测试

Swagger UI不仅提供了API文档，还可以用于接口测试。在Swagger UI界面中，每个API端点都有一个”Try it out”按钮，点击后可以输入参数并执行API请求，查看响应结果。

然而，对于更复杂的测试场景，我们可以结合其他工具来实现自动化测试。以下是一些常用的方法：

使用Swagger Codegen生成测试代码

Swagger Codegen可以根据Swagger规范生成客户端代码，包括测试代码。以下是使用Swagger Codegen生成测试代码的步骤：

1. 首先，确保已经安装了Swagger Codegen。可以从https://github.com/swagger-api/swagger-codegen下载。
2. 使用以下命令生成测试代码：

首先，确保已经安装了Swagger Codegen。可以从https://github.com/swagger-api/swagger-codegen下载。

使用以下命令生成测试代码：
  2. java -jar swagger-codegen-cli.jar generate \
  3.   -i http://localhost:8080/v2/api-docs \
  4.   -l java \
  5.   -o ./generated-code \
  6.   --library resttemplate \
  7.   --api-package com.example.client.api \
  8.   --model-package com.example.client.model \
  9.   --invoker-package com.example.client.invoker \
  10.   --group-id com.example \
  11.   --artifact-id swagger-java-client \
  12.   --artifact-version 1.0.0
复制代码

这个命令会根据提供的API文档生成Java客户端代码。

使用Spring Boot Test进行测试

Spring Boot Test提供了强大的测试支持，可以结合Swagger进行API测试：
  2. package com.example.swaggerspringbootdemo;
  4. import com.example.swaggerspringbootdemo.controller.User;
  5. import com.fasterxml.jackson.databind.ObjectMapper;
  6. import org.junit.jupiter.api.Test;
  7. import org.springframework.beans.factory.annotation.Autowired;
  8. import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
  9. import org.springframework.boot.test.context.SpringBootTest;
  10. import org.springframework.http.MediaType;
  11. import org.springframework.test.web.servlet.MockMvc;
  12. import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
  14. import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
  15. import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
  17. @SpringBootTest
  18. @AutoConfigureMockMvc
  19. public class UserControllerTest {
  21.     @Autowired
  22.     private MockMvc mockMvc;
  24.     @Autowired
  25.     private ObjectMapper objectMapper;
  27.     @Test
  28.     public void testCreateUser() throws Exception {
  29.         User user = new User("John", "Doe", "john.doe@example.com");
  31.         mockMvc.perform(MockMvcRequestBuilders.post("/api/users")
  32.                 .contentType(MediaType.APPLICATION_JSON)
  33.                 .content(objectMapper.writeValueAsString(user)))
  34.                 .andExpect(status().isCreated())
  35.                 .andExpect(jsonPath("$.firstName").value("John"))
  36.                 .andExpect(jsonPath("$.lastName").value("Doe"))
  37.                 .andExpect(jsonPath("$.email").value("john.doe@example.com"));
  38.     }
  40.     @Test
  41.     public void testGetUserById() throws Exception {
  42.         // First, create a user
  43.         User user = new User("Jane", "Doe", "jane.doe@example.com");
  44.         String response = mockMvc.perform(MockMvcRequestBuilders.post("/api/users")
  45.                 .contentType(MediaType.APPLICATION_JSON)
  46.                 .content(objectMapper.writeValueAsString(user)))
  47.                 .andReturn().getResponse().getContentAsString();
  49.         // Extract the user ID from the response
  50.         Long userId = objectMapper.readTree(response).get("id").asLong();
  52.         // Then, get the user by ID
  53.         mockMvc.perform(MockMvcRequestBuilders.get("/api/users/{id}", userId))
  54.                 .andExpect(status().isOk())
  55.                 .andExpect(jsonPath("$.firstName").value("Jane"))
  56.                 .andExpect(jsonPath("$.lastName").value("Doe"))
  57.                 .andExpect(jsonPath("$.email").value("jane.doe@example.com"));
  58.     }
  60.     @Test
  61.     public void testUpdateUser() throws Exception {
  62.         // First, create a user
  63.         User user = new User("Bob", "Smith", "bob.smith@example.com");
  64.         String response = mockMvc.perform(MockMvcRequestBuilders.post("/api/users")
  65.                 .contentType(MediaType.APPLICATION_JSON)
  66.                 .content(objectMapper.writeValueAsString(user)))
  67.                 .andReturn().getResponse().getContentAsString();
  69.         // Extract the user ID from the response
  70.         Long userId = objectMapper.readTree(response).get("id").asLong();
  72.         // Update the user
  73.         User updatedUser = new User("Bob", "Johnson", "bob.johnson@example.com");
  74.         mockMvc.perform(MockMvcRequestBuilders.put("/api/users/{id}", userId)
  75.                 .contentType(MediaType.APPLICATION_JSON)
  76.                 .content(objectMapper.writeValueAsString(updatedUser)))
  77.                 .andExpect(status().isOk())
  78.                 .andExpect(jsonPath("$.firstName").value("Bob"))
  79.                 .andExpect(jsonPath("$.lastName").value("Johnson"))
  80.                 .andExpect(jsonPath("$.email").value("bob.johnson@example.com"));
  81.     }
  83.     @Test
  84.     public void testDeleteUser() throws Exception {
  85.         // First, create a user
  86.         User user = new User("Alice", "Williams", "alice.williams@example.com");
  87.         String response = mockMvc.perform(MockMvcRequestBuilders.post("/api/users")
  88.                 .contentType(MediaType.APPLICATION_JSON)
  89.                 .content(objectMapper.writeValueAsString(user)))
  90.                 .andReturn().getResponse().getContentAsString();
  92.         // Extract the user ID from the response
  93.         Long userId = objectMapper.readTree(response).get("id").asLong();
  95.         // Then, delete the user
  96.         mockMvc.perform(MockMvcRequestBuilders.delete("/api/users/{id}", userId))
  97.                 .andExpect(status().isNoContent());
  99.         // Verify that the user has been deleted
  100.         mockMvc.perform(MockMvcRequestBuilders.get("/api/users/{id}", userId))
  101.                 .andExpect(status().isNotFound());
  102.     }
  103. }
复制代码

在这个测试类中，我们使用了Spring Boot Test的MockMvc来测试API端点。每个测试方法都测试了一个特定的API操作，包括创建、获取、更新和删除用户。

使用Postman进行自动化测试

Postman是一个流行的API测试工具，可以与Swagger集成，实现自动化测试：

1. 从Swagger UI导出API规范：访问http://localhost:8080/v2/api-docs将JSON响应保存为文件
2. 访问http://localhost:8080/v2/api-docs
3. 将JSON响应保存为文件
4. 在Postman中导入API规范：打开Postman点击”Import”按钮选择保存的JSON文件
5. 打开Postman
6. 点击”Import”按钮
7. 选择保存的JSON文件
8. 创建测试集合：在Postman中，选择导入的API为每个端点创建测试请求添加测试脚本，例如：
9. 在Postman中，选择导入的API
10. 为每个端点创建测试请求
11. 添加测试脚本，例如：

从Swagger UI导出API规范：

• 访问http://localhost:8080/v2/api-docs
• 将JSON响应保存为文件

在Postman中导入API规范：

• 打开Postman
• 点击”Import”按钮
• 选择保存的JSON文件

创建测试集合：

• 在Postman中，选择导入的API
• 为每个端点创建测试请求
• 添加测试脚本，例如：
  2. pm.test("Status code is 200", function () {
  3.     pm.response.to.have.status(200);
  4. });
  6. pm.test("Response has user data", function () {
  7.     var jsonData = pm.response.json();
  8.     pm.expect(jsonData).to.have.property('firstName');
  9.     pm.expect(jsonData).to.have.property('lastName');
  10.     pm.expect(jsonData).to.have.property('email');
  11. });
复制代码

1. 运行测试集合：点击”Runner”按钮选择要运行的测试集合配置运行参数点击”Run”按钮执行测试
2. 点击”Runner”按钮
3. 选择要运行的测试集合
4. 配置运行参数
5. 点击”Run”按钮执行测试

• 点击”Runner”按钮
• 选择要运行的测试集合
• 配置运行参数
• 点击”Run”按钮执行测试

使用REST Assured进行测试

REST Assured是一个Java库，专门用于测试RESTful API。它可以与Spring Boot测试框架结合使用：

首先，添加REST Assured依赖：
  2. <dependency>
  3.     <groupId>io.rest-assured</groupId>
  4.     <artifactId>rest-assured</artifactId>
  5.     <version>4.3.3</version>
  6.     <scope>test</scope>
  7. </dependency>
复制代码

然后，创建测试类：
  2. package com.example.swaggerspringbootdemo;
  4. import com.example.swaggerspringbootdemo.controller.User;
  5. import io.restassured.http.ContentType;
  6. import org.junit.jupiter.api.BeforeEach;
  7. import org.junit.jupiter.api.Test;
  8. import org.springframework.boot.test.context.SpringBootTest;
  9. import org.springframework.boot.web.server.LocalServerPort;
  11. import static io.restassured.RestAssured.*;
  12. import static org.hamcrest.Matchers.*;
  14. @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
  15. public class UserControllerRestAssuredTest {
  17.     @LocalServerPort
  18.     private int port;
  20.     @BeforeEach
  21.     public void setUp() {
  22.         baseURI = "http://localhost";
  23.         port = this.port;
  24.     }
  26.     @Test
  27.     public void testCreateUser() {
  28.         User user = new User("John", "Doe", "john.doe@example.com");
  30.         given()
  31.                 .contentType(ContentType.JSON)
  32.                 .body(user)
  33.                 .when()
  34.                 .post("/api/users")
  35.                 .then()
  36.                 .statusCode(201)
  37.                 .body("firstName", equalTo("John"))
  38.                 .body("lastName", equalTo("Doe"))
  39.                 .body("email", equalTo("john.doe@example.com"));
  40.     }
  42.     @Test
  43.     public void testGetUserById() {
  44.         // First, create a user
  45.         User user = new User("Jane", "Doe", "jane.doe@example.com");
  46.         Long userId = given()
  47.                 .contentType(ContentType.JSON)
  48.                 .body(user)
  49.                 .when()
  50.                 .post("/api/users")
  51.                 .then()
  52.                 .extract()
  53.                 .path("id");
  55.         // Then, get the user by ID
  56.         given()
  57.                 .when()
  58.                 .get("/api/users/{id}", userId)
  59.                 .then()
  60.                 .statusCode(200)
  61.                 .body("firstName", equalTo("Jane"))
  62.                 .body("lastName", equalTo("Doe"))
  63.                 .body("email", equalTo("jane.doe@example.com"));
  64.     }
  66.     @Test
  67.     public void testUpdateUser() {
  68.         // First, create a user
  69.         User user = new User("Bob", "Smith", "bob.smith@example.com");
  70.         Long userId = given()
  71.                 .contentType(ContentType.JSON)
  72.                 .body(user)
  73.                 .when()
  74.                 .post("/api/users")
  75.                 .then()
  76.                 .extract()
  77.                 .path("id");
  79.         // Update the user
  80.         User updatedUser = new User("Bob", "Johnson", "bob.johnson@example.com");
  81.         given()
  82.                 .contentType(ContentType.JSON)
  83.                 .body(updatedUser)
  84.                 .when()
  85.                 .put("/api/users/{id}", userId)
  86.                 .then()
  87.                 .statusCode(200)
  88.                 .body("firstName", equalTo("Bob"))
  89.                 .body("lastName", equalTo("Johnson"))
  90.                 .body("email", equalTo("bob.johnson@example.com"));
  91.     }
  93.     @Test
  94.     public void testDeleteUser() {
  95.         // First, create a user
  96.         User user = new User("Alice", "Williams", "alice.williams@example.com");
  97.         Long userId = given()
  98.                 .contentType(ContentType.JSON)
  99.                 .body(user)
  100.                 .when()
  101.                 .post("/api/users")
  102.                 .then()
  103.                 .extract()
  104.                 .path("id");
  106.         // Then, delete the user
  107.         given()
  108.                 .when()
  109.                 .delete("/api/users/{id}", userId)
  110.                 .then()
  111.                 .statusCode(204);
  113.         // Verify that the user has been deleted
  114.         given()
  115.                 .when()
  116.                 .get("/api/users/{id}", userId)
  117.                 .then()
  118.                 .statusCode(404);
  119.     }
  120. }
复制代码

在这个测试类中，我们使用REST Assured的流畅API来测试REST端点。每个测试方法都测试了一个特定的API操作，并验证了响应状态码和内容。

最佳实践

在使用Swagger2.0和Spring Boot 2.0构建API文档管理系统时，以下是一些最佳实践：

1. 保持API文档的更新

API文档应该与代码保持同步。为了实现这一点，可以：

• 在代码中使用Swagger注解，而不是单独维护文档。
• 在CI/CD流程中添加验证步骤，确保API文档与实际代码一致。
• 定期审查API文档，确保其准确性和完整性。

2. 使用语义化的HTTP状态码

使用适当的HTTP状态码可以帮助API消费者更好地理解API的响应：

• 200 OK：请求成功。
• 201 Created：资源创建成功。
• 204 No Content：请求成功，但没有返回内容。
• 400 Bad Request：客户端请求错误。
• 401 Unauthorized：需要身份验证。
• 403 Forbidden：服务器拒绝请求。
• 404 Not Found：请求的资源不存在。
• 500 Internal Server Error：服务器内部错误。

3. 提供详细的错误信息

当API返回错误时，提供详细的错误信息可以帮助开发者快速定位问题：
  2. @ApiOperation(value = "Get a user by Id", response = User.class)
  3. @ApiResponses(value = {
  4.         @ApiResponse(code = 200, message = "Successfully retrieved user"),
  5.         @ApiResponse(code = 404, message = "User not found with the provided ID")
  6. })
  7. @GetMapping("/{id}")
  8. public ResponseEntity<?> getUserById(
  9.         @ApiParam(value = "User id from which user object will retrieve", required = true) @PathVariable Long id) {
  10.     User user = userMap.get(id);
  11.     if (user == null) {
  12.         return ResponseEntity.status(HttpStatus.NOT_FOUND)
  13.                 .body(new ErrorResponse("User not found", "User with ID " + id + " does not exist"));
  14.     }
  15.     return ResponseEntity.ok(user);
  16. }
复制代码

4. 使用版本控制

API版本控制可以帮助管理API的变化，避免破坏现有客户端：
  2. @Api(value = "User Management System v1", description = "Operations pertaining to user in User Management System v1")
  3. @RestController
  4. @RequestMapping("/api/v1/users")
  5. public class UserControllerV1 {
  6.     // Controller implementation
  7. }
  9. @Api(value = "User Management System v2", description = "Operations pertaining to user in User Management System v2")
  10. @RestController
  11. @RequestMapping("/api/v2/users")
  12. public class UserControllerV2 {
  13.     // Controller implementation
  14. }
复制代码

5. 使用API分组

对于大型项目，使用API分组可以帮助组织和管理API：
  2. @Bean
  3. public Docket publicApi() {
  4.     return new Docket(DocumentationType.SWAGGER_2)
  5.             .groupName("public")
  6.             .select()
  7.             .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller.public"))
  8.             .paths(PathSelectors.any())
  9.             .build()
  10.             .apiInfo(publicApiInfo());
  11. }
  13. @Bean
  14. public Docket privateApi() {
  15.     return new Docket(DocumentationType.SWAGGER_2)
  16.             .groupName("private")
  17.             .select()
  18.             .apis(RequestHandlerSelectors.basePackage("com.example.swaggerspringbootdemo.controller.private"))
  19.             .paths(PathSelectors.any())
  20.             .build()
  21.             .apiInfo(privateApiInfo());
  22. }
复制代码

6. 添加安全配置

保护API文档和API端点，防止未授权访问：
  2. @Override
  3. protected void configure(HttpSecurity http) throws Exception {
  4.     http
  5.         .authorizeRequests()
  6.             .antMatchers("/swagger-ui.html").hasRole("DEVELOPER")
  7.             .antMatchers("/swagger-resources/**").hasRole("DEVELOPER")
  8.             .antMatchers("/v2/api-docs").hasRole("DEVELOPER")
  9.             .antMatchers("/webjars/**").hasRole("DEVELOPER")
  10.             .antMatchers("/api/public/**").permitAll()
  11.             .antMatchers("/api/private/**").hasRole("USER")
  12.             .anyRequest().authenticated()
  13.         .and()
  14.         .formLogin()
  15.         .and()
  16.         .httpBasic();
  17. }
复制代码

7. 使用注解提供详细的文档

使用Swagger注解提供详细的API文档：
  2. @ApiOperation(value = "Create a new user", notes = "Creates a new user with the provided details. The email address must be unique.")
  3. @ApiResponses(value = {
  4.         @ApiResponse(code = 201, message = "User created successfully", response = User.class),
  5.         @ApiResponse(code = 400, message = "Invalid input", response = ErrorResponse.class),
  6.         @ApiResponse(code = 409, message = "Email address already in use", response = ErrorResponse.class)
  7. })
  8. @PostMapping
  9. public ResponseEntity<?> createUser(
  10.         @ApiParam(value = "User details", required = true) @Valid @RequestBody UserDto userDto) {
  11.     // Implementation
  12. }
复制代码

8. 使用DTO进行数据传输

使用DTO（Data Transfer Object）进行数据传输，而不是直接暴露实体类：
  2. @ApiModel(description = "User data transfer object")
  3. public class UserDto {
  4.     @ApiModelProperty(notes = "The user's first name", required = true)
  5.     @NotBlank
  6.     private String firstName;
  7.    
  8.     @ApiModelProperty(notes = "The user's last name", required = true)
  9.     @NotBlank
  10.     private String lastName;
  11.    
  12.     @ApiModelProperty(notes = "The user's email address", required = true)
  13.     @Email
  14.     @NotBlank
  15.     private String email;
  16.    
  17.     // Getters and setters
  18. }
复制代码

9. 实现自动化测试

实现API的自动化测试，确保API的功能和性能：
  2. @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
  3. @AutoConfigureMockMvc
  4. public class UserControllerTest {
  6.     @Autowired
  7.     private MockMvc mockMvc;
  9.     @Autowired
  10.     private ObjectMapper objectMapper;
  12.     @Test
  13.     public void testCreateUser() throws Exception {
  14.         UserDto userDto = new UserDto("John", "Doe", "john.doe@example.com");
  16.         mockMvc.perform(post("/api/users")
  17.                 .contentType(MediaType.APPLICATION_JSON)
  18.                 .content(objectMapper.writeValueAsString(userDto)))
  19.                 .andExpect(status().isCreated())
  20.                 .andExpect(jsonPath("$.firstName").value("John"))
  21.                 .andExpect(jsonPath("$.lastName").value("Doe"))
  22.                 .andExpect(jsonPath("$.email").value("john.doe@example.com"));
  23.     }
  24. }
复制代码

10. 集成到CI/CD流程

将API文档生成和测试集成到CI/CD流程中，确保代码变更不会破坏API：
  2. # .gitlab-ci.yml example
  3. stages:
  4.   - build
  5.   - test
  6.   - deploy
  8. build:
  9.   stage: build
  10.   script:
  11.     - ./mvnw clean compile
  13. test:
  14.   stage: test
  15.   script:
  16.     - ./mvnw test
  17.     - ./mvnw swagger2markup:convertSwagger2markup
  19. deploy:
  20.   stage: deploy
  21.   script:
  22.     - ./mvnw deploy
  23.   only:
  24.     - master
复制代码

总结

Swagger2.0与Spring Boot 2.0的整合为API开发和管理带来了许多好处。通过本文的介绍，我们了解了如何从零开始构建一个现代化的API文档管理系统，提升开发效率与团队协作能力，并快速实现接口自动化测试。

主要内容包括：

1. 环境准备：介绍了所需的开发环境和工具，以及如何创建Spring Boot项目。
2. 整合步骤：详细介绍了如何添加Swagger依赖、配置Swagger、创建API控制器和模型类。
3. 高级功能：介绍了API分组、自定义Swagger UI、安全配置和全局参数配置等高级功能。
4. 接口自动化测试：介绍了如何使用Swagger Codegen、Spring Boot Test、Postman和REST Assured进行API测试。
5. 最佳实践：提供了一些在使用Swagger2.0和Spring Boot 2.0构建API文档管理系统时的最佳实践。

通过整合Swagger2.0和Spring Boot 2.0，我们可以：

• 提高开发效率：自动生成API文档，减少手动编写文档的工作量。
• 增强团队协作：提供统一的API文档平台，促进团队成员之间的协作。
• 加速测试过程：通过Swagger UI和其他工具，快速测试API端点。
• 提高API质量：通过自动化测试，确保API的功能和性能。
• 改善用户体验：提供清晰、准确的API文档，帮助开发者更好地理解和使用API。

总之，Swagger2.0与Spring Boot 2.0的整合是一个强大的组合，可以帮助我们构建现代化的API文档管理系统，提升开发效率与团队协作能力，并快速实现接口自动化测试。
工具集
「七転び八起き（ななころびやおき）」
回复

使用道具 举报

返回列表 发新帖
您需要登录后才可以回帖 登录 | 立即注册
高级模式
B Color Image Link Quote Code Smilies

本版积分规则