OpenAPI 3.0 — это широко используемая спецификация для проектирования и документирования RESTful API. В этой статье мы рассмотрим различные методы настройки файла OpenAPI 3.0 в приложении Spring Boot. Мы предоставим примеры кода и обсудим необходимые шаги для интеграции документации OpenAPI в ваши проекты Spring Boot.

1. Использование Springfox:
   Springfox — популярная библиотека, интегрирующая Swagger со Spring Boot. Он предоставляет аннотации и конфигурации для автоматического создания документации OpenAPI. Вот как это можно настроить:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build();
    }
}

2. Использование Springdoc:
   Springdoc — еще одна библиотека, обеспечивающая поддержку OpenAPI 3.0 в приложениях Spring Boot. Он предлагает более лаконичный подход к настройке по сравнению со Springfox. Вот пример его настройки:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("My API").version("1.0.0"))
            .addTagsItem(new Tag().name("users").description("Operations related to users"));
    }
}

3. Использование Spring Boot Starter для OpenAPI:
   Spring Boot Starter для OpenAPI — это официальный проект Spring, который предоставляет простой способ включить поддержку OpenAPI 3.0 в ваше приложение Spring Boot. Вот пример его настройки:

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

4. Ручная настройка.
   Если вы предпочитаете ручной подход, вы можете настроить OpenAPI 3.0, не полагаясь на какие-либо библиотеки. Вы можете определить спецификацию OpenAPI в файле YAML или JSON и вручную загрузить ее в свое приложение. Вот пример:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        String openApiFilePath = "classpath:openapi.yaml";
        OpenAPIParser openAPIParser = new OpenAPIParser();
        ParseOptions options = new ParseOptions();
        options.setResolve(true);
        SwaggerParseResult parseResult = openAPIParser.readLocation(openApiFilePath, null, options);

        if (parseResult.getOpenAPI() != null) {
            return parseResult.getOpenAPI();
        } else {
            throw new RuntimeException("Failed to load OpenAPI definition");
        }
    }
}

Настроить файл OpenAPI 3.0 в приложении Spring Boot можно различными методами. В этой статье мы рассмотрели четыре различных подхода, включая использование популярных библиотек, таких как Springfox и Springdoc, а также официального Spring Boot Starter для OpenAPI. Кроме того, мы обсудили метод ручной настройки для тех, кто предпочитает более индивидуальный подход. Выберите метод, который лучше всего соответствует требованиям вашего проекта, и начните эффективно документировать свои RESTful API.