middle

Как документировать REST API с помощью Swagger/OpenAPI?

OpenAPI Specification (ранее Swagger Specification) — стандарт описания REST API в формате JSON или YAML. Swagger — набор инструментов для работы с OpenAPI (Swagger UI, Swagger Editor, Swagger Codegen).

Основные инструменты

Swagger UI — интерактивная веб-документация с возможностью отправки запросов.
OpenAPI Generator / Swagger Codegen — генерация клиентов и серверов из спецификации.
Springdoc-openapi — библиотека для автоматической генерации OpenAPI-документации в Spring Boot.

Настройка в Spring Boot (springdoc-openapi)

Пример

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

После подключения доступны:

http://localhost:8080/swagger-ui.html — Swagger UI.
http://localhost:8080/v3/api-docs — OpenAPI-спецификация в JSON.

Аннотации для документирования

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "Управление пользователями")
public class UserController {

    @Operation(
        summary = "Получить пользователя по ID",
        description = "Возвращает полную информацию о пользователе"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Пользователь найден",
            content = @Content(schema = @Schema(implementation = UserDto.class))),
        @ApiResponse(responseCode = "404", description = "Пользователь не найден",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    })
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUser(
            @Parameter(description = "ID пользователя", example = "42")
            @PathVariable Long id) {
        return ResponseEntity.ok(userService.findById(id));
    }

    @Operation(summary = "Создать нового пользователя")
    @ApiResponse(responseCode = "201", description = "Пользователь создан")
    @PostMapping
    public ResponseEntity<UserDto> createUser(
            @RequestBody @Valid CreateUserRequest request) {
        UserDto created = userService.create(request);
        URI location = URI.create("/api/users/" + created.id());
        return ResponseEntity.created(location).body(created);
    }
}

Документирование модели:

@Schema(description = "Запрос на создание пользователя")
public record CreateUserRequest(
    @Schema(description = "Имя пользователя", example = "Иван Петров")
    @NotBlank String name,

    @Schema(description = "Email", example = "ivan@example.com")
    @Email String email,

    @Schema(description = "Возраст", minimum = "18", maximum = "120")
    @Min(18) Integer age
) {}

Глобальная конфигурация:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("User Service API")
                .version("1.0.0")
                .description("API для управления пользователями"))
            .addSecurityItem(new SecurityRequirement().addList("Bearer"))
            .components(new Components()
                .addSecuritySchemes("Bearer",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")));
    }
}

На собеседовании: нужно знать разницу между OpenAPI (спецификация) и Swagger (инструменты), уметь назвать ключевые аннотации (@Operation, @Tag, @Schema). Частая ошибка — путать Swagger и OpenAPI или не знать про springdoc-openapi для Spring Boot 3.

#rest