こんにちは、原田です。
今回はSwagger-PHPをLaravelのプロジェクトに導入し、APIをドキュメント化してみます。
ドキュメントって修正があるたびに更新したりと、面倒なことが多いのでSwaggerを使って楽にしたいと思います。
Swaggerインストール
今回はLaravelプロジェクトで使用するのでSwagger-PHPを使います。
composerを使って入れていきます。
$ composer require zircote/swagger-php
メモリ不足でエラーになる場合は下記のコマンドで試してみてください。
$ COMPOSER_MEMORY_LIMIT=-1 composer require zircote/swagger-php
設定ファイルの作成
APIの基本情報を記述したファイルを作成します。
このファイルの内容がディレクトリ内のコントローラーに適用されます。
app/swagger.php
<?php
/**
* @OA\Info(
* title="API Example",
* description="description",
* version="1.0.0",
* )
*
* @OA\Server(
* description="OpenApi host",
* url="http://localhost:8080"
* )
*/コントローラー作成
次にテスト用にコントローラーを作成します。
$ php artisan make:controller TestController
作成されたTestControllerにSwaggerのアノテーションを記載していきます。
/**
* @OA\Get(
* path="/test",
* summary="Swaggerのテスト用",
* @OA\Response(
* response=200,
* description="OK",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="message",
* type="string",
* description="レスポンスパラメータの例を記載"
* )
* )
* ),
* @OA\Response(
* response=400,
* description="Bad Request",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="message",
* type="string",
* description="レスポンスパラメータの例を記載"
* )
* )
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="message",
* type="string",
* description="レスポンスパラメータの例を記載"
* )
* )
* )
* )
*/
public function index()
{
//
}上記の記述は基本的な項目のみですが、いろんなアノテーションが用意されてます。
詳細な仕様はこちらから確認できます。
https://swagger.io/specification/
json生成
下記コマンドでjsonを生成します。出力先はpublic/にapiフォルダを作成し、こちらに出力されるようにします。
$ ./vendor/bin/openapi ./app --output ./public/api/openapi.json
Swagger UIのインストール
生成したjsonファイルを表示ドキュメントとして表示するためにSwaggerUIを使用します。
こちらからソースをダウンロードできます。
https://github.com/swagger-api/swagger-ui
dist配下のファイルをプロジェクトにpublic/swaggerを作成しコピーします。
public/swagger/index.htmlの以下１文を修正し、生成したjsonを読み込むようにします。
変更前url: "https://petstore.swagger.io/v2/swagger.json",
変更後
url: "../api/openapi.json",
それではブラウザで確認してみましょう。
http://{ホスト名}/swagger/index.htmlで表示することができます。
おわりに
Swaggerを使ってドキュメントを生成できるようにしてみました。
Swaggerを入れることでAPIの開発とドキュメント作成が同時に進められるっていうのも便利ですね。
