SwaggerでLaravel5のAPIドキュメントを作成するメモ

新規プロジェクトのLaravel製APIにSwaggerを試してみたのでメモです

swagger-phpをcomposerで追加

$ composer require zircote/swagger-php

実装メモ

github.com

www.marcoraddatz.com

こちら等を参考にさせていただきながらやってみます

基本情報の作成

app/swagger.phpを作成

<?php

/**
 * @SWG\Swagger(
 *     host="192.168.33.41/",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="0.9.0",
 *         title="api documentのテスト",
 *     ),
 * )
 * @SWG\Tag(
 *   name="user",
 *   description="ユーザーに関するAPI"
 * )
 */

コントローラーにコメントを書く

例えばユーザー情報を取得するメソッドに適当に書いてみる

    /**
     * Display the specified resource.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
     /**
      * @SWG\Get(
      *     path="/user/{id}",
      *     description="user情報を取得する",
      *     produces={"application/json"},
      *     tags={"user"},
      *     @SWG\Parameter(
      *         name="id",
      *         description="userのid",
      *         in="path",
      *         required=true,
      *         type="string"
      *     ),
      *     @SWG\Response(
      *         response=200,
      *         description="OK"
      *     ),
      *     @SWG\Response(
      *         response=404,
      *         description="NG"
      *     )
      * )
      */
    public function show($version)
    {

・
・
・

swagger-uiをダウンロードする

github.com

Zipをダウンロード、解凍して出てきたdistディレクトリをpublic/swagger-uiとして保存

本番環境を意識して、.gitignoreするなりWebサーバーの方でアクセス制限するなりしておきます。

index.html書き換え

public/swagger-ui/index.htmlの76行目辺り

  url: "http://petstore.swagger.io/v2/swagger.json",

を

  url: "swagger.json",

に変更しておきます

swaggerコマンド実行

$ vendor/bin/swagger app/ -o public/swagger-ui/swagger.json

Swagger-PHP 2.0.13
------------------
    get /user/{id}
-----------------------
1 operations documented
-----------------------
Written to /usr/share/www/html/public/swagger-ui/swagger.json