インストール
composer require 'drupal/openapi:8.x-2.3'
composer require 'drupal/openapi:8.x-2.1'
概要
OpenAPIモジュールは、OpenAPI（旧Swagger）仕様標準に準拠した機械可読なAPIドキュメントを生成します。これにより、Drupalサイト向けのAPIドキュメントの自動生成、クライアントコード生成、APIテスト機能が可能になります。
これはOpenAPI仕様を生成するためのコアフレームワークとプラグインシステムを提供する基盤モジュールです。使用するには、Drupal CoreのRESTモジュール用のOpenAPI RESTやJSON:APIモジュール用のOpenAPI JSON:APIなどの統合モジュールをインストールする必要があります。
生成されたOpenAPI仕様は、Swagger Editor、Swagger Codegen、Postman、その他様々なAPIドキュメントビューアなどのツールで使用できます。また、OpenAPI UIモジュールと統合して、ReDocやSwagger UIなどのツールを使用したブラウザ内ドキュメント閲覧機能を提供します。
Features
- Drupal REST API向けにJSON形式のOpenAPI 2.0（Swagger）仕様ドキュメントを生成
- 他のモジュールが異なるAPI実装用のAPIドキュメントジェネレータを提供できるプラグインベースのアーキテクチャ
- Basic Auth、OAuth2、CSRFトークン認証を含む複数の認証方式のビルトインサポート
- 利用可能なすべてのAPIジェネレータを一覧表示し、仕様のダウンロードやドキュメントの探索へのリンクを提供する管理インターフェース
- Drupal内でインタラクティブなAPIドキュメント閲覧を可能にするOpenAPI UIモジュールとの統合
- 特定のEntityタイプやBundleに対する仕様を生成するためのフィルタリングオプション
- 有効な認証プロバイダに基づくセキュリティ定義の自動検出
- 生成された仕様のスキーマ検証とクリーニングユーティリティ
Use Cases
開発者向けAPIドキュメントの生成
OpenAPIを使用してDrupalサイトの包括的なREST APIドキュメントを生成します。統合モジュール（openapi_restまたはopenapi_jsonapi）とともにモジュールをインストールした後、開発者は/openapi/rest?_format=jsonまたは/openapi/jsonapi?_format=jsonにアクセスして完全なAPI仕様をダウンロードできます。このJSONファイルはSwagger Editorにインポートしてインタラクティブに閲覧したり、Swagger Codegenを使用して様々なプログラミング言語のクライアントライブラリを生成したりできます。
インタラクティブAPIエクスプローラー
OpenAPIをOpenAPI UIおよびopenapi_ui_redocモジュールと組み合わせて、ブラウザ内でのAPIドキュメントインターフェースを提供します。/admin/config/services/openapi/redoc/restまたは/admin/config/services/openapi/redoc/jsonapiに移動して、APIをインタラクティブに探索できます。開発者はブラウザを離れることなく、利用可能なすべてのエンドポイント、リクエスト/レスポンススキーマ、認証要件を確認できます。
APIクライアントコードの生成
OpenAPI仕様をダウンロードし、Swagger CodegenまたはOpenAPI Generatorを使用して、JavaScript、Python、PHP、Javaなど多くの言語でDrupal API用のクライアントライブラリを自動的に作成できます。これにより型安全なAPI利用が保証され、Drupalサイトと統合するアプリケーションの開発時間が短縮されます。
Entityタイプ別のドキュメント
URLでオプションを渡すことで、特定のEntityタイプやBundleのドキュメントを生成できます。例えば、/openapi/rest?_format=json&options[entity_type_id]=node&options[bundle_name]=articleは記事Nodeのみのドキュメントを生成します。これは特定のAPI利用者向けに焦点を絞ったドキュメントを作成する際に便利です。
PostmanでのAPIテスト
生成されたOpenAPI仕様をPostmanや同様のAPIテストツールにインポートします。仕様にはエンドポイントURL、認証要件、リクエストパラメータ、期待されるレスポンスが含まれているため、テストコレクションの作成やAPI動作の検証が容易になります。
カスタムAPIドキュメントジェネレータ
カスタムAPIモジュールや独自のAPI実装用にカスタムOpenAPIジェネレータプラグインを作成します。OpenApiGeneratorBaseを拡張し、getPaths()、getDefinitions()、getTags()、getApiName()などのメソッドを実装して、API構造に一致する仕様を生成します。プラグインはモジュールのsrc/Plugin/openapi/OpenApiGeneratorディレクトリに@OpenApiGeneratorアノテーションとともに配置します。
Tips
- 開発者とステークホルダーの両方に適したクリーンでレスポンシブなドキュメントインターフェースには、openapi_ui_redocモジュールを使用してください
- entity_type_idやbundle_nameなどのURLオプションを使用して大規模なAPI仕様をフィルタリングし、特定のユースケース向けに焦点を絞ったドキュメントを生成できます
- 開発中のクイックアクセス用に直接JSONダウンロードURL（/openapi/rest?_format=json）をブックマークしておくと便利です
- 生成された仕様には、サイトの設定から自動検出されたscheme（http/https）、host、basePathの情報が含まれます
- セキュリティ定義は有効な認証モジュールに基づいて自動的に設定されます - basic_authやSimple OAuthを有効にすると、それらの認証方式が含まれます
- カスタムジェネレータでは「exclude」オプションを使用して特定のEntityタイプやBundleを仕様から除外できます
Technical Details
Admin Pages 1
/admin/config/services/openapi
利用可能なすべてのAPIドキュメントジェネレータを一覧表示するOpenAPIのメイン管理ページです。このページではOpenAPI機能の概要と、仕様のダウンロードやインタラクティブなドキュメントの表示へのリンクを提供します。
権限 1
Hooks 1
hook_openapi_generator_alter
モジュールがOpenAPIジェネレータプラグインの定義を変更できるようにします。プラグイン検出時に呼び出され、利用可能なジェネレータを変更します。
Troubleshooting 5
ジェネレータプラグインを提供する統合モジュールをインストールしてください。Core REST用にはopenapi_rest、JSON:API用にはopenapi_jsonapiをインストールします。これらの統合モジュールがないと、OpenAPIモジュールにはドキュメント化するAPIがありません。
ユーザーが「access openapi api docs」権限を持っていることを確認してください。この権限はOpenAPI管理ページの表示とAPI仕様のダウンロードに必要です。
対応するAPIモジュール（RESTまたはJSON:API）が有効になっており、リソースが設定されていることを確認してください。RESTの場合は/admin/config/services/restでRESTリソースを有効にして設定します。JSON:APIの場合は、EntityタイプがJSON:APIアクセス用に有効になっていることを確認します。
openapi_uiモジュールとopenapi_ui_redocやopenapi_ui_swagger_uiなどのUIライブラリモジュールをインストールしてください。これらのモジュールがないと、仕様のダウンロードリンクのみが利用可能です。
モジュールはDrupalに登録された認証プロバイダを自動的に検出します。basic_auth、oauth2（Simple OAuth）、または他の認証モジュールが適切に有効化され設定されていることを確認してください。
Security Notes 3
- 「access openapi api docs」権限はAPIドキュメントへのアクセスを制御します。APIドキュメントはサイトのデータ構造を明らかにする可能性があるため、この権限を誰に付与するか慎重に検討してください
- API仕様は現在のユーザーの権限に基づいて生成され、ユーザーが見ることはできてもアクセスできないエンドポイントが含まれる場合があります
- OpenAPIドキュメントを公開する際は注意してください。サイトのAPI構造に関する詳細情報が提供されるため、偵察に使用される可能性があります