Springdoc apidocs по умолчанию отображает YAML вместо JSON

На чтение 3 мин Опубликовано 20.09.2024

Вопрос или проблема

У меня есть приложение Spring Boot 3.x, использующее Springdoc для генерации документации Swagger и OpenAPI. Когда я обращаюсь к /api-docs, он возвращает схему в формате JSON. Чтобы получить формат YAML, мне нужно добавить .yaml к URL, например /api-docs.yaml.

Есть ли способ настроить Springdoc так, чтобы он по умолчанию возвращал схему YAML при доступе к /api-docs, без необходимости добавлять .yaml к URL? Я хочу, чтобы YAML был форматом по умолчанию вместо JSON.

Я попытался добавить пользовательский контроллер, но это не сработало. Я также добавлял фильтр в свой класс конфигурации sprindoc, но ничего не работает, у меня все равно остается JSON как формат по умолчанию.

Ответ или решение

Конечно, вы можете настроить Springdoc для возврата схемы в формате YAML по умолчанию вместо JSON. По умолчанию Springdoc генерирует документацию в формате JSON, но есть способ изменить это поведение.

Вот шаги, которые вам нужно выполнить, чтобы вернуть YAML по умолчанию при доступе к /api-docs:

Создайте специальный контроллер: Вы можете создать собственный контроллер, который будет перехватывать запросы к /api-docs и возвращать YAML, преобразовав JSON в YAML.

import io.swagger.v3.core.util.Json;
import io.swagger.v3.oas.models.OpenAPI;
import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;

@RestController
public class ApiDocsController {

    @Autowired
    private OpenAPI openAPI;

    @GetMapping(value = "/api-docs", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public ResponseEntity<String> getApiDocs() {
        try {
            // Преобразование OpenAPI в JSON
            String json = Json.pretty(openAPI);
            // Преобразование JSON в YAML
            String yaml = new Yaml().dump(new ObjectMapper().readValue(json, Object.class));
            return ResponseEntity.ok()
                    .contentType(MediaType.parseMediaType("text/x-yaml"))
                    .body(yaml);
        } catch (Exception e) {
            return ResponseEntity.internalServerError().body("Ошибка при генерации YAML: " + e.getMessage());
        }
    }
}

Установка необходимых зависимостей: Убедитесь, что вы добавили необходимые зависимости для работы с YAML в вашем pom.xml:

<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>1.29</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-yaml</artifactId>
    <version>2.12.5</version>
</dependency>

Удалите или измените конфигурацию Springdoc: Если у вас уже есть конфигурация Springdoc, проверьте, нет ли там конфликта с вашим новым контроллером. Убедитесь, что настройки, которые могли бы перенаправить стандартный путь /api-docs, корректны.
Тестирование: После добавления контроллера и зависимостей протестируйте конечную точку /api-docs. Теперь она должна возвращать документацию в формате YAML.

Таким образом, с помощью пользовательского контроллера вы можете настроить выходные данные ваших API-документов в формате YAML по умолчанию.