42. 如何在Spring Boot中集成Swagger生成API文档？

PangHu大约 3 分钟

在Spring Boot中集成Swagger可以帮助你自动生成REST API文档，使开发者和用户能够更方便地查看和测试API。Swagger通常与springdoc-openapi或springfox一起使用，不过springfox的支持相对较弱，因此目前推荐使用springdoc-openapi。以下是如何在Spring Boot项目中集成Swagger以生成API文档的详细步骤。

1. 引入依赖

首先，在pom.xml中引入springdoc-openapi的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

这个依赖包括了Spring Doc和Swagger UI的功能，它将自动扫描你的Spring Boot项目中的API并生成Swagger文档。

2. 配置Swagger

在默认情况下，springdoc-openapi不需要额外的配置，集成完成后，你可以直接访问API文档。Swagger UI的默认访问路径是/swagger-ui.html。

2.1 自定义Swagger配置（可选）

你可以通过配置类进一步自定义Swagger的行为，比如设置API信息、定制路径等。以下是一个自定义Swagger配置的示例：

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("My API")
                        .description("API Documentation for My Application")
                        .version("v1.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("Project Documentation")
                        .url("https://example.com/docs"));
    }
}

3. 使用Swagger注解

Swagger支持使用注解来描述API的行为和参数，使生成的文档更加详细和精确。以下是常用的Swagger注解及其用法示例：

3.1 `@Operation`和`@Parameter`

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @Operation(summary = "Get user by ID", description = "Retrieve a user by their ID")
    @GetMapping("/users/{id}")
    public User getUserById(
            @Parameter(description = "ID of the user to be retrieved", required = true)
            @PathVariable Long id) {
        return new User(id, "John Doe");
    }

    @Operation(summary = "Search users", description = "Search for users based on name and age")
    @GetMapping("/users/search")
    public List<User> searchUsers(
            @RequestParam String name,
            @RequestParam(required = false) Integer age) {
        return List.of(new User(1L, "John Doe"), new User(2L, "Jane Doe"));
    }
}

3.2 `@Schema`和`@ApiResponse`

import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@Schema(description = "User entity")
public class User {

    @Schema(description = "Unique identifier of the user", example = "1")
    private Long id;

    @Schema(description = "Full name of the user", example = "John Doe")
    private String name;

    // getters and setters
}

@RestController
public class UserController {

    @Operation(summary = "Get user by ID")
    @ApiResponse(responseCode = "200", description = "Successfully retrieved user")
    @ApiResponse(responseCode = "404", description = "User not found")
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        // logic to get user by id
        return new User(id, "John Doe");
    }
}

4. 访问Swagger UI

启动Spring Boot应用后，你可以通过访问以下URL查看生成的Swagger UI：

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

在Swagger UI中，你可以看到所有API的列表，并且可以直接在线测试API。

5. 总结

通过springdoc-openapi，在Spring Boot中集成Swagger变得非常简单。你只需要添加依赖，并且可以选择性地进行一些自定义配置，Swagger就会自动扫描和生成API文档。结合Swagger注解，API文档可以更加详尽和精确，有助于开发和维护RESTful服务。

这使得你的API文档不仅易于访问，而且对其他开发者和用户来说也更加清晰、可用。