У меня есть проект (Spring Boot App + Kotlin), для которого я хотел бы иметь спецификацию Open API 3.0 (желательно на YAML). Библиотеки Springfox хороши, но они генерируют Swagger 2.0 JSON. Каков наилучший способ создания спецификации Open Api 3.0 из аннотаций в моих контроллерах? Единственный способ написать это с нуля?

21
ladyskynet 1 Май 2019 в 17:55

4 ответа

Лучший ответ

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

Он автоматически развертывает swagger-ui в приложении с весенней загрузкой.

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

Добавьте библиотеку в список зависимостей вашего проекта (дополнительная настройка не требуется)

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.2.32</version>
  </dependency>
8
ouled saber 1 Мар 2020 в 09:39

Вы можете посмотреть spring-restdocs и restdocs-api-spec.

spring-restdocs использует тестовый подход к документации API, который имеет много преимуществ по сравнению с подходом, основанным на интроспекции, который использует spring-fox. restdocs-api-spec - это расширение для spring-restdocs, которое добавляет поддержку спецификации API. В настоящее время он поддерживает OpenAPI2 OpenAPI3 и Postman.

4
Mathias Dpunkt 1 Май 2019 в 18:29

Я решил реализовать свой собственный генератор https://github.com/jrcodeza/spring-openapi может ты тоже можешь это проверить. Он основан на отражении и поддерживает javax и весенние аннотации. Он также генерирует модель наследования (с дискриминаторами) на основе аннотаций Джексона. Кроме того, вы можете определить свои собственные перехватчики, если хотите изменить процесс генерации (например, когда у вас есть свои собственные аннотации и вам нужно настроить сгенерированные разделы схемы). Вы можете использовать его в режиме исполнения или как плагин maven. Существует также OpenAPI3 для генератора клиента java, который генерирует модель из спецификации openapi3. Опять же, он генерирует также аннотации Javax и аннотации Джексона для правильного наследования.

3
Jakub Remenec 24 Окт 2019 в 18:35

Вы также можете обратиться к https://www.baeldung.com/spring-rest-openapi-documentation который предоставляет руководство по реализации OpenAPI 3.0 с приложением SpringBoot 1.x или 2.x с использованием springdoc-openapi.

Подводя итог, вы просто добавляете зависимость maven для springdoc-openapi в свое приложение и, когда вы запускаете bootRun, переходите к пути http: // сервер: порт / v3 / api-docs.yaml / и Вы загрузите в yaml файл спецификации Open API 3.0, сгенерированный из кода вашего приложения.

Вы можете сделать некоторые другие вещи с помощью springdoc-openapi, обратившись к следующему, когда ваше приложение SpringBoot работает:

0
Jonathan Lee 21 Апр 2020 в 01:51