LaravelのREST APIをSwaggerでドキュメント化した

REST APIのドキュメントはSwaggerで作るのがスタンダードらしいのでやってみた。

– 手順 –

１．swagger

①swagger-phpを入れる

Larevelのプロジェクトの下でcomposerで入れる。

#cd /var/www/blood
#composer require zircote/swagger-php

1 2	#cd /var/www/blood #composer require zircote/swagger-php

②swagger-uiを入れる

https://github.com/swagger-api/swagger-ui

のdistの中身を、Laravelプロジェクト/publicの下にswagger-uiディレクトリを作ってコピーする。

２．Laravelプロジェクトの設定

①swagger-xxx.phpの作成。

appの下に作った。

<?php

/**
 * @SWG\Swagger(
 *     host="xxxxx.xxx.net:9000",
 *     basePath="/api",
 *     schemes={"http"},
 *     @SWG\Info(
 *         version="1.0",
 *         title="血圧管理手帳のAPIドキュメント",
 *     ),
 *     @SWG\SecurityScheme(
 *       securityDefinition="MyHeaderAuthentication",
 *       type="basic",
 *     )
 * )
 * @SWG\Definition(
 *    definition="Blood",
 *    @SWG\Property(property="date",type="string",format="yyyy-MM-dd",description="日付"),
 *    @SWG\Property(property="time",type="string",format="HH:mm:dd",description="時間"),
 *    @SWG\Property(property="wakeup",type="boolean",description="起床"),
 *    @SWG\Property(property="max",type="integer",description="最高血圧"),
 *    @SWG\Property(property="min",type="integer",description="最低血圧"),
 *    @SWG\Property(property="pulse",type="integer",description="脈拍"),
 *    @SWG\Property(property="weight",type="number",format="float",description="体重"),
 *    @SWG\Property(property="ck",type="boolean",description="服薬チェック"),
 *    @SWG\Property(property="memo",type="string",description="メモ")
 * )
 */

<?php

/**

* @SWG\Swagger(

* host="xxxxx.xxx.net:9000",

* basePath="/api",

* schemes={"http"},

* @SWG\Info(

* version="1.0",

* title="血圧管理手帳のAPIドキュメント",

* ),

* @SWG\SecurityScheme(

* securityDefinition="MyHeaderAuthentication",

* type="basic",

* )

* @SWG\Definition(

* definition="Blood",

* @SWG\Property(property="date",type="string",format="yyyy-MM-dd",description="日付"),

* @SWG\Property(property="time",type="string",format="HH:mm:dd",description="時間"),

* @SWG\Property(property="wakeup",type="boolean",description="起床"),

* @SWG\Property(property="max",type="integer",description="最高血圧"),

* @SWG\Property(property="min",type="integer",description="最低血圧"),

* @SWG\Property(property="pulse",type="integer",description="脈拍"),

* @SWG\Property(property="weight",type="number",format="float",description="体重"),

* @SWG\Property(property="ck",type="boolean",description="服薬チェック"),

* @SWG\Property(property="memo",type="string",description="メモ")

* )

②Controlerの修正

各コントローラーにswaggerのアノテーションを書いていく。

    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Response
     *
     * @SWG\Get(
     *     path="/blood",
     *     summary="先頭100件データを取得する",
     *     produces={"application/json"},
     *     tags={"blood"},
     *     security={{
     *       "MyHeaderAuthentication":{}
     *     }},
     *     @SWG\Response(
     *         response=200,
     *         description="OK",
     *         @SWG\Schema(
     *             type="array",
     *             @SWG\Items(ref="#/definitions/Blood"))
     *     ),
     *     @SWG\Response(
     *         response=404,
     *         description="NOT-FOUND"
     *     ),
     *     @SWG\Response(
     *         response=403,
     *         description="Auth error",
     *     ),
     * )
     */
    public function index()
    {

/**

* Display a listing of the resource.

* @return \Illuminate\Http\Response

* @SWG\Get(

* path="/blood",

* summary="先頭100件データを取得する",

* produces={"application/json"},

* tags={"blood"},

* security={{

* "MyHeaderAuthentication":{}

* }},

* @SWG\Response(

* response=200,

* description="OK",

* @SWG\Schema(

* type="array",

* @SWG\Items(ref="#/definitions/Blood"))

* ),

* @SWG\Response(

* response=404,

* description="NOT-FOUND"

* ),

* @SWG\Response(

* response=403,

* description="Auth error",

* ),

* )

public function index()

{

③swagger.jsonファイルの出力

さっき入れたswagger-uiの下に出力した。

#vendor/bin/swagger /var/www/blood/app/ -o public/swagger-ui/

1	#vendor/bin/swagger /var/www/blood/app/ -o public/swagger-ui/

３．確認

①１．②で入れたswagger-uiのindex.htmlを書き換える。

79行目あたり

url: "http://petstore.swagger.io/v2/swagger.json",
↓
url: "http://サーバー/swagger-ui/swagger.json",

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

↓

url: "http://サーバー/swagger-ui/swagger.json",

②ブラウザで確認

http://サーバー/swagger-ui/

でswagger.jsonを見るとドキュメントとして見れる。

できた。(∩´∀｀)∩

アノテーションの記述とかにエラーがあるとエラーのボタンが表示される。

ボタンを押すと別ウィンドウでエラーの箇所と内容が表示される。

で、Visual StudioのREST APIクライアントの追加で作成したswagger.json読み込んでみたが、

エラーになった。(´・ω・｀)

ウィンドウが発行とかなってる。

これってREST APIにアクセスする便利なクラスを作ってくれるものではないのかな。。。(´ヘ｀;)　う～ん・・・

—

参考サイト

http://blog.hrendoh.com/how-to-use-swagger-php-with-laravel/

http://swagger.io/specification/#securitySchemeObject

日	月	火	水	木	金	土
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	31

LaravelのREST APIをSwaggerでドキュメント化した

– 手順 –

１．swagger

①swagger-phpを入れる

②swagger-uiを入れる

２．Laravelプロジェクトの設定

①swagger-xxx.phpの作成。

②Controlerの修正

③swagger.jsonファイルの出力

３．確認

①１．②で入れたswagger-uiのindex.htmlを書き換える。

②ブラウザで確認

共有:

いいね: