Как создать файл YAPL OpenAPI 3.0 из существующего Spring REST API?

У меня есть существующий Spring REST API, для которого я хочу создать YAML файл OpenAPI 3.0, а не Swagger 2.0 JSON/YAML?

Поскольку на данный момент SpringFox не поддерживает генерацию YAML. Он генерирует JSON с Swagger 2.0 (который соответствует спецификации OPEN API 3.0).

Кроме того, есть https://github.com/openapi-tools/swagger-maven-plugin, но он не поддерживает Spring Rest.

Я попробовал подключаемый модуль Kongchen spring-maven-plugin, который может генерировать файл YAML, но с определением Swagger 2.0, а не с OPEN API 3.0, например:

swagger: "2.0"
info:
  description: "Test rest project"
  version: "1.0"
  title: "Some desc"
  termsOfService: "http://swagger.io/terms/"
  contact:
    name: "Rest Support"
    url: "http://www.swagger.io/support"
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "example.com"
basePath: "/api/"

Итак, мой вопрос, как я могу сгенерировать файл OPEN API YAML, например:

openapi: 3.0.0
info:
  description: Some desc
  version: "1.0"
  title: Test rest project
  termsOfService: http://swagger.io/terms/
  contact:
    name: Rest Support
    url: http://www.swagger.io/support
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

В настоящее время я использую swagger-maven-plugin для создания файла YAML с определением Swagger 2.0 и преобразования его в определение Open API 3.0 с использованием swagger2openapi по адресу https://mermade.org.uk/openapi-converter.

Вопрос 1: Может ли Spring-Maven-плагин захватить io.swagger.v3.oas.annotations для создания YAML?

Вопрос 2: Каков наилучший способ создания YAML с определениями OPEN API в проекте Spring MVC?

Вопрос 3: Можно ли использовать io.swagger.v3.oas с проектами Spring или только для проектов JAX-RS?

Ответы

Ответ 1

в последнее время мы использовали java-библиотеку springdoc-openapi. Это помогает автоматизировать создание документации API с использованием проектов весенней загрузки.

Он автоматически развертывает swagger-ui в приложении с весенней загрузкой. Документация будет доступна в формате HTML, используя официальные [swagger-ui jars]:

Страница Swagger UI должна быть доступна по адресу http://server: port/context-path/swagger-ui.html, а описание OpenAPI будет доступно по следующему URL-адресу для формата json: HTTP://сервер: порт/контекст-путь/v3/API-документы

  • сервер: имя сервера или IP-адрес
  • порт: порт сервера
  • context-path: контекстный путь приложения

Документация также может быть доступна в формате yaml по следующему пути: /v3/api-docs.yml Добавьте библиотеку в список зависимостей вашего проекта (дополнительная настройка не требуется)

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

Ответ 2

Библиотека springdoc-openapi, поддерживает OpenAPI 3 с помощью spring-boot: