swagger-php CLI で Swagger Specification を生成してみた

前回に続き 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 に読み込むことができた.便利!

次回は

アノテーションをちゃんと覚えようと思う.複雑すぎて心折れそうだけど swagger-php のドキュメントを読みながら.

IntelliJ Swagger Plugin

あったら良いなー!と思ったけどまだ無くて,Wishlist に出てた.皆で Vote しましょう!

関連エントリー