Как создать YAML-файл OpenAPI 3.0 из существующего Spring REST API? - PullRequest
Новая
       35

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

0 голосов
/ 28 февраля 2019

У меня есть существующий 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: "support@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "example.com"
basePath: "/api/"

Поэтому мой вопрос заключается в том, как сгенерировать YAML-файл OPEN API, например:

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: support@swagger.io
  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-plugin захватывает io.swagger.v3.oas.annotations для генерации YAML?

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

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

1 Ответ

0 голосов
/ 03 августа 2019

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

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

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

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

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

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