引き続き swagger-php を試している．前回 swagger-php のサンプルアノテーションを使って Swagger Specification を生成するところまで確認したので，次は実際にアノテーションを書いてみようと思って格闘していた．

deprecated って言われた

http://zircote.com/swagger-php/

swagger-php のドキュメントを参考にアノテーションを書いていたら，以下のエラーが出てしまった．調べたところ，このドキュメントは Swagger 1.x 系のもので，現在主流の Swagger 2.x 系だと deprecated になっているアノテーションだとわかった．gh-pages ブランチを見ると最近メンテされてなさそうだし，swagger-php で Swagger 2.x 系に対応したドキュメントはどこにあるんだろう？

まぁ今後 @SWG\Resource() と @SWG\Api() となっていたら「あ！ Swagger 1.x 系だな」とわかるし，学びがあって良かった（と思うことにする）．

[WARN] The annotation @SWG\Resource() is deprecated. Found in xxx
For more information read the migration guide: https://github.com/zircote/swagger-php/blob/2.x/docs/Migrating-to-v2.md

[WARN] The annotation @SWG\Api() is deprecated. Found in xxx
For more information read the migration guide: https://github.com/zircote/swagger-php/blob/2.x/docs/Migrating-to-v2.md

swagger-php Examples

https://github.com/zircote/swagger-php/tree/master/Examples

ドキュメントが無さそうだったので，swagger-php の Examples を参考にした．Examples はちゃんと Swagger 2.x 系になっていた．全ての記法が網羅されているわけではないけど，最低限の Swagger Specification なら書けそうな気がする．

アノテーションを書いてみた

ローカルの Vagrant に PHP でサンプル API を実装して，アノテーションを書いてみた．前回同様に swagger-php CLI で Swagger Specification を出力して，Swagger UI で API をコールするところまで確認できた．

まず Swagger Specification の共通的な部分を書いた．

SWAGGER OBJECT
INFO OBJECT
CONTACT OBJECT
LICENSE OBJECT
EXTERNAL DOCUMENTATION OBJECT

    /**
     * @SWG\Swagger(
     *   schemes={"http"},
     *   host="192.168.33.22",
     *   basePath="/api/v1",
     *   @SWG\Info(
     *       version="1.0.0",
     *       title="Swagger Sample",
     *       description="This is a documents for swagger sample server.",
     *       @SWG\Contact(
     *           email="swagger@example.com"
     *       ),
     *       @SWG\License(
     *           name="Apache 2.0",
     *           url="http://www.apache.org/licenses/LICENSE-2.0.html"
     *       )
     *   ),
     *   @SWG\ExternalDocumentation(
     *       description="Find out more about Swagger",
     *       url="http://swagger.io"
     *   )
     * )
     */

次に API 単位の部分を書いた．モデル関連のアノテーションは無くても動いたので省略した．

PATHS OBJECT
PATH ITEM OBJECT
OPERATION OBJECT

    /**
     * @SWG\Get(
     *   path="/projects",
     *   summary="list projects",
     *   tags={"project"},
     *   description="list projects",
     *   @SWG\Response(
     *     response=200,
     *     description="A list with projects"
     *   ),
     *   @SWG\Response(
     *     response="400",
     *     description="Invalid tag value",
     *   )
     * )
     */

参考情報

Swagger UI はローカルで直接 dist/index.html を参照していたので，Vagrant 上に実装したサンプル API は CORS の制限でコールできなかった．一時的に Nginx の設定で CORS を通すようにして，無事動くようになった．念のためメモしておく．

server {
    （中略）
    location ~ \.php$ {
        if ($request_method = 'GET') {
          add_header 'Access-Control-Allow-Origin' '*';
          add_header 'Access-Control-Allow-Credentials' 'true';
          add_header 'Access-Control-Allow-Methods' 'GET';
          add_header 'Access-Control-Allow-Headers' 'DNT, X-CustomHeader, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type';
        }
    }
    （中略）
}