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 と統合するためのライブラリ
  • OpenAPI デモ アプリケーションを使用した Spring-boot。
    • デモ アプリケーションのソース コード。
    • OpenAPI 3 を使用した Spring Boot 2 Web MVC のデモ。
    • OpenAPI 3 を使用した Spring Boot 2 WebFlux のデモ。
    • 機能エンドポイント OpenAPI 3 を使用した Spring Boot 2 WebFlux のデモ。
    • OpenAPI 3 を使用した Spring Boot 2 と Spring Hateoas のデモ。
  • swagger-ui を使用しない Spring Boot 3.x プロジェクトへのライブラリの統合:
  • @ControllerAdvice を使用した REST のエラー処理
  • API 情報とセキュリティに関するドキュメントの追加
  • 注釈付きコントローラーによる spring-webflux のサポート
• 謝辞
  • 貢献者
  • 追加のサポート

完全なドキュメント

導入

springdoc-openapi Java ライブラリは、Spring Boot プロジェクトを使用した API ドキュメントの生成の自動化に役立ちます。 springdoc-openapi は、実行時にアプリケーションを調べて、Spring 構成、クラス構造、さまざまなアノテーションに基づいて API セマンティクスを推測することによって機能します。

このライブラリは、JSON/YAML および HTML 形式のページでドキュメントを自動的に生成します。生成されたドキュメントは、 swagger-apiアノテーションを使用して補完できます。

このライブラリは以下をサポートしています。

• オープンAPI 3
• Spring-boot v3 (Java 17 および Jakarta EE 9)
• JSR-303、特に @NotNull、@Min、@Max、および @Size 用。
• Swagger-ui
• OAuth2
• GraalVM ネイティブ イメージ

次のビデオではライブラリを紹介しています。

• https://youtu.be/utRxyPfFlDw

spring-boot v3 をサポートするには、必ず springdoc-openapi v2 を使用してください。

これはコミュニティベースのプロジェクトであり、Spring Framework Contributors (Pivotal) によって保守されていません。

はじめる

springdoc-openapi を spring-boot および swagger-ui と統合するためのライブラリ

• swagger-ui を Spring Boot 3.x アプリケーションに自動的にデプロイします
• ドキュメントは、公式 swagger-ui jar を使用して HTML 形式で入手できます。
• Swagger UI ページは http://server: port/context-path/swagger-ui.html で利用できるようになり、OpenAPI の説明は次の URL で json 形式で利用できるようになります: http://server:port/context -パス/v3/api-docs
  • server : サーバー名またはIP
  • port : サーバーポート
  • context-path : アプリケーションのコンテキスト パス
• ドキュメントは、パス/v3/api-docs.yamlから 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 '

• この手順はオプションです。HTML 形式の Swagger ドキュメントのカスタム パスの場合、カスタム springdoc プロパティを Spring-Boot 構成ファイルに追加します。

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

OpenAPI デモ アプリケーションを使用した Spring-boot。

デモ アプリケーションのソース コード。

OpenAPI 3 を使用した Spring Boot 3 Web MVC のデモ。

OpenAPI 3 を使用した Spring Boot 3 WebFlux のデモ。

機能エンドポイント OpenAPI 3 を使用した Spring Boot 3 WebFlux のデモ。

Spring Boot 3 と Spring Cloud Function Web MVC のデモ。

Spring Boot 3 と Spring Cloud Function WebFlux のデモ。

Spring Boot 3 と Spring Cloud Gateway のデモ。

swagger-ui を使用しない Spring Boot 3.x プロジェクトへのライブラリの統合:

• ドキュメントは、json 形式の URL で入手できます: http://server: port/context-path/v3/api-docs
  • server : サーバー名またはIP
  • port : サーバーポート
  • context-path : アプリケーションのコンテキスト パス
• ドキュメントは、パス/v3/api-docs.yamlから 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 '

• この手順はオプションです。Json 形式の OpenAPI ドキュメントのカスタム パスの場合、カスタム springdoc プロパティをスプリングブート構成ファイルに追加します。

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

• この手順はオプションです。 springdoc-openapiエンドポイントを無効にする場合は、カスタム springdoc プロパティをspring-boot構成ファイルに追加します。

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

@ControllerAdvice を使用した REST のエラー処理

ドキュメントを自動的に生成するには、すべてのメソッドが注釈 @ResponseStatus を使用して HTTP コード応答を宣言していることを確認してください。

API 情報とセキュリティに関するドキュメントの追加

このライブラリは、Spring-Boot アプリケーションの自動構成パッケージを使用して、Spring Bean のアノテーション OpenAPIDefinition および Info をスキャンします。これらのアノテーションは、API 情報: タイトル、バージョン、ライセンス、セキュリティ、サーバー、タグ、セキュリティ、および externalDocs を宣言します。ドキュメント生成のパフォーマンスを向上させるには、Spring マネージド Bean 内で@OpenAPIDefinitionおよび@SecuritySchemeアノテーションを宣言します。

注釈付きコントローラーによる spring-webflux のサポート

• ドキュメントは、パス /v3/api-docs.yaml から 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 '

• この手順はオプションです。HTML 形式の Swagger ドキュメントのカスタム パスの場合、カスタム 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 プロジェクトをサポートしていただきありがとうございます。