Swagger3でLaravelのAPIをドキュメント化する

Swagger3でLaravelのAPIをドキュメント化する

こんにちは、原田です。

今回は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の以下1文を修正し、生成したjsonを読み込むようにします。

変更前
url: "https://petstore.swagger.io/v2/swagger.json",

変更後
url: "../api/openapi.json",

それではブラウザで確認してみましょう。
http://{ホスト名}/swagger/index.htmlで表示することができます。

おわりに

Swaggerを使ってドキュメントを生成できるようにしてみました。
Swaggerを入れることでAPIの開発とドキュメント作成が同時に進められるっていうのも便利ですね。

エンジョイワークスでは一緒に働くエンジニアを募集しております!
採用情報はこちらWantedlyも覗いてみてください!

一覧へ戻る

最新記事