Swaggerについて

はじめに

業務で使うのでSwaggerについて調べました。備忘録(殴り書き)です。

改めて整理します

http://swagger.io/

参考

RESTful APIとは?

RESTful APIとは何なのか

リソース指向アーキテクチャ(ROA)とは何なのか

Swaggerの概要をまとめてみた。

OpenAPI (Swagger) 超入門

LaravelプロジェクトのAPIをswaggerを使ってドキュメント化

Swaggerの記法まとめ

前提

✅RESTful API

RESTの原則に則って構築されたWebシステムのHTTPでの呼び出しインターフェースのこと。※広義でREST APIとほぼ同じ

URIに規律が生まれるため、様々なメリットを享受できる。

✅リソース指向アーキテクチャ(ROA)

リソース指向アーキテクチャ(Resource Oriented Architecture)とは、それ自体を参照するに値するものを「リソース」として定義し、リソースを中心に考えるアーキテクチャのこと。

Swaggerについて

✅OpenAPI

OpenAPIとは、RESTful APIを記述するためのフォーマットのこと。

✅Swagger

Swaggerとは、OpenAPIを用いてREST APIを設計する際に使用するツールセットのこと。(オープンソースのフレームワーク)
APIのドキュメントを楽に作成できる。

✅Swagger Spec

Swagger Spec を書いておけば自動的にドキュメント生成までしてくれる。記述はYAMLかJSONか選べる。

🙄プロジェクトではswagger.jsonを作成して使ってました

✅Swagger Editer

リンク

Swaggerファイルの生成や編集を行うためのツール。ブラウザ上で動く。

✅Swagger UI

Swagger-Specを読み込んで、HTML形式でドキュメントを生成するためのツール。

以下公式デモ

Laravelで使う

インストール

$ composer require zircote/swagger-php:2.0.13

composer.jsonに以下のように追記される。

"zircote/swagger-php": "2.0.13"

参考:composerのrequireコマンドでパッケージを後から追加する

👆バージョン指定は3だとvendor/bin配下にswaggerが作成されないため。

参考:Composer のインストール先と、composer.json に記載されたライブラリのダウンロード先について

👆composer.jsonのあるディレクトリにvendorが作られて、その中にインストールされる。

ファイルの作成

app/swaggerDefine.php

<?php

/**
 * @SWGSwagger(
 *     host="localhost:8000", // http://は不要
 *     schemes={"http", "https"},
 *     @SWGInfo(
 *         version="1.0",
 *         title="xxx のAPIドキュメント",
 *     ),
 * )
 */

Controller.php

hogeアクションを追加

<?php
namespace App\Http\Controllers;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;

class Controller extends BaseController
{
  use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
  /**
   * @SWG\Get(
   *     path="/hoge/{hogeID}",
   *     description="hogeを取得する",
   *     produces={"application/json"},
   *     tags={"hoge"},
   *     @SWG\Parameter(
   *         name="hogeID",
   *         description="hogeのID",
   *         in="path",
   *         required=true,
   *         type="string"
   *     ),
   *     @SWG\Response(
   *         response=200,
   *         description="Success"
   *     ),
   *     @SWG\Response(
   *         response=404,
   *         description="Parameter error"
   *     ),
   *     @SWG\Response(
   *         response=403,
   *         description="Auth error",
   *     ),
   * )
   */
  public function hoge($userID)
  {
      return response()->json(['hoge' => 1]);
  }
}

コマンド実行でpublic/swaggerが作成される※拡張子なし

$ vendor/bin/swagger ./app -o ./public/swagger
// $ vendor/bin/swagger {swagger-xxx.phpを記述したディレクトリ} -o {swagger.json出力先ディレクトリ}

ブラウザでドキュメント確認

http://localhost:8000/swaggerにアクセス。json形式で表示されます。

swagger-uiのリポジトリからDist部分をダウンロードしてpublic/swaggerディレクトリ以下に置く

👇http://localhost/swagger/にアクセスするとサンプルが表示される。

uiを配置した後にコマンドを打つと.jsonファイルで出力されるので再度実行
※public/swagger/swagger.jsonが作成される

$ vendor/bin/swagger ./app -o ./public/swagger

index.htmlを編集してswagger.jsonファイルを読み込む

const ui = SwaggerUIBundle({
  // url: "https://petstore.swagger.io/v2/swagger.json",
  url: "http://localhost:8000/swagger/swagger.json",

再度確認

🙄いい感じに表示されましたね!!

このままだと検証できないのでルーティングを設定。

web.phpに以下を追記

Route::get('hoge/{id?}',"Controller@hoge");

Controller.phpを編集

  public function hoge($id)
  {
      return response()->json(['hoge' => $id]);
  }

http://localhost:8000/hoge/123にアクセスするとjson形式で取得できるのを事前に確認。

http://localhost/swaggerにアクセスしてswagger-uiで確認。

🙄確認がswagger-ui上でできました。

api.phpを使って動作するようにする

swaggerDefine.phpを編集

<?php
/**
 * @SWG\Swagger(
 *     host="localhost:8000",
 *     basePath="/api",
 *     schemes={"http"},
 *     @SWG\Info(
 *         version="1.0",
 *         title="swagger-app",
 *     ),
 *     @SWG\SecurityScheme(
 *       securityDefinition="MyHeaderAuthentication",
 *       type="basic",
 *     )
 * )
 */

swagger.jsonを再度作成

$ vendor/bin/swagger ./app -o ./public/swagger

api.phpに以下追記

Route::get('hoge/{id?}',"Controller@hoge");

http://localhost:8000/api/hoge/1にアクセス

http://localhost:8000/swagger/で確認

POST送信してみる

api.phpに追記

Route::post('hogePost/{id?}',"Controller@hogePost");

Controller.phpに追記

  /**
   * @SWG\Post(
   *     path="/hogePost/{id}",
   *     description="hogeをポストする",
   *     produces={"application/json"},
   *     tags={"hogePost"},
   *     @SWG\Parameter(
   *         name="id", // pathの{id}と紐づく
   *         description="hogeのID",
   *         in="path",
   *         required=true,
   *         type="string"
   *     ),
   *     @SWG\Response(
   *         response=200,
   *         description="Success"
   *     ),
   *     @SWG\Response(
   *         response=404,
   *         description="Parameter error"
   *     ),
   *     @SWG\Response(
   *         response=403,
   *         description="Auth error",
   *     ),
   * )
   */
  public function hogePost($id)
  {
      return response()->json(['hoge' => $id]);
  }

curlコマンドで確認

$ curl -X POST "http://localhost:8000/api/hogePost/112" -H "accept: application/json" -H "Content-Type: application/json"

出力結果

{"hoge":"112"}

Swagger-uiでも確認

おわりに

参考になりそうな記事は最初にまとめておいたので、隙間時間にチェックする!

※8/15追記※

自身の環境でSwaggerを試すことができました。post送信もGUI上で試せるのは便利ですね◎

コメントを残す