ガイド
仕様書
OpenAPI仕様書を自動生成する方法を学びます。
組み込みのOpenAPI仕様書生成機能を使うと、コードを一切変更することなく仕様書を生成できます。
php artisan orion:specs
このコマンドは、storage/app/specsディレクトリ内にspecs.jsonファイルを作成します。
カスタマイズ
InfoとServers
仕様書のinfoフィールドとserversフィールドは、orion.php設定ファイルから読み込まれます。
'specs' => [
'info' => [
'title' => env('APP_NAME'),
'description' => null,
'terms_of_service' => null,
'contact' => [
'name' => null,
'url' => null,
'email' => null,
],
'license' => [
'name' => null,
'url' => null,
],
'version' => '1.0.0',
],
'servers' => [
['url' => env('APP_URL').'/api', 'description' => 'Default Environment'],
],
],
設定ファイルをまだ公開していない場合は、次のコマンドを実行して公開できます。
php artisan vendor:publish --tag=orion-config
ファイルパス
ファイルを別のパス(例: storage/app/specs/example.yaml)に保存したい場合は、--pathオプションを指定することで簡単にカスタマイズできます。指定するパスは相対パスである点に注意してください。
php artisan orion:specs --path="specs/example.yaml"
ファイル形式
デフォルトでは、仕様書ファイルは.json形式で保存されます。ただし、--formatオプションを指定するだけで.yaml形式で保存することも可能です。
php artisan orion:specs --format="yaml"
既存の仕様書
すでにカスタムエンドポイントとそのOpenAPI仕様書がある場合は、既存の仕様書ファイルをstorage/appディレクトリ内の任意の場所に置き、コマンドに--pathオプションを指定するだけで済みます。標準エンドポイントの仕様書が生成され、既存の(カスタムの)仕様書とマージされます。指定するパスは相対パスである点に注意してください。
php artisan orion:specs --path="specs/existing-specs.json"
現時点では、ジェネレーターは標準の(Orionが提供する)エンドポイントのみをサポートしています。独自に作成したカスタムエンドポイントの仕様書は生成されません。
ただし、今後のリリースで対応できるようにする計画があります。