読者です 読者をやめる 読者になる 読者になる

swagger-php と Swagger UI で API をコールしてみた

Swagger PHP

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

deprecated って言われた

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

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

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

ローカルの VagrantPHP でサンプル 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';
        }
    }
    (中略)
}

Web API Advent Calendar

今日の Web API Advent Calendar で Swagger の記事が上がってた!

Amazon API Gateway との連携には興味があるし,それこそ Swagger のメリットかなとも思うので,試したいなー!

まとめ

少し Swagger に詳しくなった気がするw