springdoc openapi

ВАЖНО: springdoc-openapi v1.8.0 — это последняя версия с открытым исходным кодом, поддерживающая Spring Boot 2.x и 1.x.

Расширенная поддержка проекта Springdoc-openapi v1 теперь доступна для организаций, которым потребуется поддержка после 2023 года.

Для получения более подробной информации обращайтесь по адресу: [email protected].

springdoc-openapi находится в Open Collective. Если вам ❤️ этот проект, рассмотрите возможность стать спонсором.

Этот проект спонсируется

Оглавление

• Полная документация
• Введение
• Начиная
  • Библиотека для интеграции Springdoc-openapi с Spring-Boot и Swagger-UI
  • Spring-загрузка с демонстрационными приложениями OpenAPI.
    • Исходный код для демонстрационных приложений.
    • Демо Spring Boot 2 Web MVC с OpenAPI 3.
    • Демо Spring Boot 2 WebFlux с OpenAPI 3.
    • Демо Spring Boot 2 WebFlux с функциональными конечными точками OpenAPI 3.
    • Демо Spring Boot 2 и Spring Hateas с OpenAPI 3.
  • Интеграция библиотеки в проект Spring Boot 3.x без swagger-ui:
  • Обработка ошибок для REST с использованием @ControllerAdvice
  • Добавление документации по информации и безопасности API
  • поддержка Spring-Webflux с аннотированными контроллерами
• Благодарности
  • Авторы
  • Дополнительная поддержка

Полная документация

Введение

Библиотека Java Springdoc-openapi помогает автоматизировать создание документации API с помощью проектов Spring Boot. Springdoc-openapi работает, исследуя приложение во время выполнения, чтобы сделать вывод о семантике API на основе конфигураций Spring, структуры классов и различных аннотаций.

Библиотека автоматически генерирует документацию в форматах JSON/YAML и HTML. Сгенерированную документацию можно дополнить аннотациями swagger-api .

Эта библиотека поддерживает:

• ОпенAPI 3
• Spring-boot v3 (Java 17 и Jakarta EE 9)
• JSR-303, специально для @NotNull, @Min, @Max и @Size.
• Swagger-UI
• ОАутентификация 2
• Собственные образы GraalVM

В следующем видео представлена ​​библиотека:

• https://youtu.be/utRxyPfFlDw

Для поддержки Spring-Boot v3 убедитесь, что вы используете Springdoc-openapi v2.

Это проект сообщества, не поддерживаемый участниками Spring Framework (основной).

Начиная

Библиотека для интеграции Springdoc-openapi с Spring-Boot и Swagger-UI

• Автоматически развертывает swagger-ui в приложении Spring Boot 3.x.
• Документация будет доступна в формате HTML с использованием официальных jar-файлов swagger-ui.
• Страница пользовательского интерфейса Swagger должна быть доступна по адресу http://server:port/context-path/swagger-ui.html, а описание OpenAPI будет доступно по следующему URL-адресу для формата json: http://server:port/context. -path/v3/api-docs
  • server : имя или IP-адрес сервера.
  • port : порт сервера
  • context-path : контекстный путь приложения.
• Документация также может быть доступна в формате yaml по следующему пути: /v3/api-docs.yaml
• Добавьте библиотеку springdoc-openapi-ui в список зависимостей вашего проекта (дополнительная настройка не требуется):

Мавен

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Градл

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Этот шаг не является обязательным: для настраиваемого пути к документации Swagger в формате HTML добавьте настраиваемое свойство Springdoc в файл конфигурации Spring-Boot:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

Spring-загрузка с демонстрационными приложениями OpenAPI.

Исходный код для демонстрационных приложений.

Демо Spring Boot 3 Web MVC с OpenAPI 3.

Демо Spring Boot 3 WebFlux с OpenAPI 3.

Демо Spring Boot 3 WebFlux с функциональными конечными точками OpenAPI 3.

Демо Spring Boot 3 и Spring Cloud Function Web MVC.

Демо Spring Boot 3 и функция Spring Cloud WebFlux.

Демо Spring Boot 3 и Spring Cloud Gateway.

Интеграция библиотеки в проект Spring Boot 3.x без swagger-ui:

• Документация будет доступна по следующему URL-адресу в формате json: http://server:port/context-path/v3/api-docs.
  • server : имя или IP-адрес сервера.
  • port : порт сервера
  • context-path : контекстный путь приложения.
• Документация также будет доступна в формате yaml по следующему пути: /v3/api-docs.yaml
• Добавьте библиотеку в список зависимостей вашего проекта. (Никакой дополнительной настройки не требуется)

Мавен

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Градл

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Этот шаг не является обязательным: для настраиваемого пути к документации OpenAPI в формате Json добавьте настраиваемое свойство Springdoc в файл конфигурации Spring-Boot:

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• Этот шаг не является обязательным: если вы хотите отключить конечные точки springdoc-openapi , добавьте собственное свойство Springdoc в файл конфигурации spring-boot :

 # disable api-docs
springdoc.api-docs.enabled =false

Обработка ошибок для REST с использованием @ControllerAdvice

Чтобы автоматически генерировать документацию, убедитесь, что все методы объявляют ответы HTTP-кода с помощью аннотации: @ResponseStatus.

Добавление документации по информации и безопасности API

Библиотека использует автоматически настроенные пакеты приложения Spring-Boot для сканирования следующих аннотаций в Spring bean-компонентах: OpenAPIDefinition и Info. В этих аннотациях указывается информация API: название, версия, лицензия, безопасность, серверы, теги, безопасность и внешние документы. Для повышения производительности создания документации объявите аннотации @OpenAPIDefinition и @SecurityScheme в управляемом bean-компоненте Spring.

поддержка Spring-Webflux с аннотированными контроллерами

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

Мавен

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

Градл

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Этот шаг не является обязательным: для настраиваемого пути к документации Swagger в формате HTML добавьте настраиваемое свойство Springdoc в файл конфигурации Spring-Boot:

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

Библиотеки springdoc-openapi размещены в центральном репозитории Maven. Посмотреть артефакты можно в следующих местах:

Релизы:

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/.

Снимки:

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/.

Благодарности

Авторы

Springdoc-openapi актуален и регулярно обновляется благодаря ценному вкладу его участников.

Спасибо всем за вашу поддержку!

Дополнительная поддержка

• Команда Spring. Благодарим за поддержку, поделившись всеми соответствующими ресурсами, связанными с проектами Spring.
• JetBrains — Большое спасибо за поддержку проекта Springdoc-openapi.