前回に続き Swagger の話で，アノテーションから Swagger Specification を生成してみたいなと思って swagger-php を試してみた．

swagger-php

Swagger 2.0 に対応してる PHP 用のライブラリで，Composer でインストールすればすぐ使える．Swagger Specification はアプリケーションから生成したり，CLI で生成したりできる．今回はお手軽に CLI で試してみた．

Composer でインストールする

➜  ~  composer global require zircote/swagger-php
Changed current directory to /Users/xxx/.composer
Using version ~2.0 for zircote/swagger-php
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing symfony/finder (v2.7.7)
    Downloading: 100%

  - Installing doctrine/lexer (v1.0.1)
    Downloading: 100%

  - Installing doctrine/annotations (v1.2.7)
    Downloading: 100%

  - Installing zircote/swagger-php (2.0.4)
    Downloading: 100%

Writing lock file
Generating autoload files

サンプルアノテーション

README に書いてあるアノテーションを適当な PHP ファイルに書く．

/**
 * @SWG\Info(title="My First API", version="0.1")
 */

/**
 * @SWG\Get(
 *     path="/api/resource.json",
 *     @SWG\Response(response="200", description="An example resource")
 * )
 */

Swagger Specification を生成する

CLI で Swagger を実行するとカレントディレクトリに swagger.json が出力される．

➜  app git:(master) ✗ swagger

Swagger-PHP 2.0.4
-----------------
Scanning files in '/Users/xxx/app' ...
    get /api/resource.json
-----------------------
1 operations documented
-----------------------
Written to /Users/xxx/app/swagger.json

Swagger UI で読み込む

ちゃんと Swagger UI で表示できた．

f:id:kakku22:20151130190446p:plain

Dropbox を活用した

前回 Swagger Specification を Sinatra API から返すように実装したけど，非常に面倒だったので，今回は Dropbox で一時的にファイルを公開するようにした．これで Public な URL が取得できるので，簡単に Swagger UI に読み込むことができた．便利！