Swagger とその基本書式について学ぶ

Swagger とその基本書式について学ぶ

こんにちは。七色メガネです。

今日は、API の仕様書作成にとても有用な Swagger というオープンフレームについてその概念と書式を勉強し、実際に記述してみて分かった文法についてまとめて見たいと思います。

 

Swagger って?

Swagger とは

Swagger とは、RESTful API の作成を補助するオープンソースのフレームワークのことです。
また、このフレームワークにおいて標準化されているドキュメント仕様そのものを指す言葉であったりもします。

API 作成における仕様の統一を目指す Open API Initiative という団体においてこの Swagger が標準フォーマットとして採択したこともあり、特に外国では既に、API仕様におけるデファクトスタンダードの位置を築き上げています。

Swagger の形式

Swagger 仕様に従って記述されるAPI定義ファイルは、yaml 形式で記述されます。
yaml で記述されたファイルを Swagger UI や Swagger Editor などの可視化、あるいは編集のためのツールで確認すると、JSON形式で閲覧することができます。表示表現が JSON であるだけで、API への入出力が JSON に限定されている訳ではありません。

Swagger の良いところ

Swagger を使用すると、色々良いことがあります。

  • 標準フォーマットでAPI仕様を記述できる。
    開発では、ともすると各人、あるいは各プロジェクトにおける独自形式でAPI仕様書を作成してしまいがちですが、Swagger に従う、という方針を取ることで、API仕様のフォーマットを統一することができます。
  • リアルタイムで仕様書のコードチェックとビジュアライズを行ってくれる Swagger Editor というツールが提供されている。
    後述する Swagger Editor は、Swagger の仕様に従ったAPI定義書を作成するためのツールです。ブラウザで起動するこのツールは、書き込んだ内容を随時確認し、エラーチェックと可視化を行ってくれますので、仕様書の作成がとても捗ります。
  • 作成した定義書を HTML ファイルとして生成する Swagger UI というツールが提供されている。
    Editor で可視化されていた定義書のUIは、Swagger UI でドキュメントとして生成することができます。このツールを使用することで、多量の定義書も不揃いになることなく一様に管理できるようになるはずです。

次の画像は、公式ツールで提供されているサンプルAPIの定義です。
左がエディター部分で、ここに書いた内容がリアルタイムで右側にビジュアライズされていきます。

Swagger 関係の用語

  • Swagger SPEC
    Swagger の仕様のこと。(Specification)
  • Swagger YAML
    Swagger SPEC に乗っ取って、実際にAPI定義を記述したファイルのこと。yaml形式。
  • Swagger UI
    Swagger SPEC に基づいたドキュメントをHTML形式で閲覧・生成するツールのこと。
  • Swagger Editor
    Swagger SPEC に基づいたドキュメントを作成できるエディタのこと。
  • Swagger Codegen
    Swagger SPEC に基づいたドキュメントから API を自動で生成するツールのこと。

Swagger YAML の書式について

では早速、Swagger SPEC に乗っ取った Swagger YAML の表現について確認していきます。

Swagger YAML は何で作成しても良いのですが、Swagger Editor が優秀なので基本的にはそれで作成することが多いかと思います。今回も Swagger Editor を使用して色々試してみます。

Swagger Editor  の起動

この Editor はブラウザで動作します。以下のURLにアクセスすることで、 Editor を起動させることができます。

https://editor.swagger.io/

業務で使用する場合は Docker 環境などを用意することで localhost で Editor を開けるようです。
が、今回はそのアプローチは取らずに通常ブラウザで記述していこうと思います。

共通設定

まず、Swagger.yaml の先頭に記述する項目についてです。

イメージはこんな感じ。

共通設定部分については、プロジェクトで開発するときには最初期以外にあまり気にすることはないと思うので、ここはざっくり見るだけにします。

  • swagger
    swagger のバージョンです。特別な理由がなければ、2.0 で大丈夫です。
  • info
    文書全体に関する設定です。いじるところは title と description くらいかなと思います。version と title が必須になります。
  • host
    ホストサーバの名称か、IPを指定します。
  • basePath
    APIが提供される時、host 名に関連づけられるパスです。
  • tags
    APIのドメインを切り出すのに使用できるタグの宣言です。メタ情報を追加できます。
  • schemas
    APIで使用するプロトコルを指定します。

エンドポイントのURLとHTTPメソッドの定義

次にAPIのエンドポイントの定義を確認します。

次の画像では、各エンドポイントの中身をリクエストとレスポンスの定義を隠して、宣言部分だけを見ています。

paths

エンドポイントの定義は、全てこの paths の下で行います。paths の下では、次の階層順序でエンドポイントを定義します。

  1. エンドポイントのURL
  2. HTTPメソッドの種類
  3. リクエストとレスポンスに関する定義( 上の画像では隠されている )

つまりこの画像の例では、

「 “/human” というURLに対して、”GET / POST” の2種類のHTTPメソッドを受け取るエンドポイントと、
“/human/{empNo}” というURLに対して、”PUT/ DELETE” を受け付けるエンドポイントを定義する」

という構成になっています。

GET/POST や PUT / DELETE が連なっていることからわかるように、HTTPメソッドが異なっていれば、URLは共用できます。

また右の画像を見てみるとGET~PUTまでが human というタグに紐づけられていることから分かるように、URLが異なっていても同一のタグを指定すると、同一のドメインとして括ることができます。

リクエストとレスポンスの定義

ではリクエストとレスポンスの定義を見ていきましょう。異なるHTTPメソッドを通して、主要な記述方法について確認します。

GET

まずはコードとUIの画像から。

  • get
    URLの次の階層にはHTTPメソッドを定義します。今回はGETです。
  • tags
    使用するタグを指定します。タグはドメインのようなイメージで、今回は事前に定義している”human”というタグを使用することで、human関係のエンドポイントをひとまとめにしています。
  • operationId
    操作の名称です。この名前は、APIの中でユニークでなければなりません。
  • produces
    生成するオブジェクトのMIMEタイプを指定します。今回はUI上でJSON形式で確認をしたいので、JSONを指定します。
    生成するオブジェクトのタイプは produces で指定し、(GETでは指定しませんが)受け取るオブジェクトのタイプは consumes で指定します。
parameters

受け取るパラメータの内容を指定します。” – (ハイフン)” で開始した1ブロックが、1つのパラメータについての定義になります。
ここではハイフンで sex と name の2つのパラメータを定義しています。

  • name
    パラメータの名称です。必須です。
  • in
    パラメータの位置を指定します。必須です。”query” , “body”, “header”, “path” が指定できます。
    今回は “query” を指定しています。query は、パラメータがURLに付属する形で提供されることを表現します。
    この指定であれば、” /human?sex=1 ” という感じでパラメータを受け取ることを想定しています。
  • description
    説明文です。
  • required
    パラメータの存在を必須にするかどうかの指定です。デフォルトでは false です。
  • type
    パラメータのタイプの指定です。必須です。string や integer, boolean などの値を指定できます。
responses

レスポンスに関する定義を行います。

  • 200 (などの数値コード)
    HTTPステータスを指定します。
  • description
    所属するブロックのステータスコードについての説明です。
  • schema
    返却するスキーマを指定します。スキーマは事前に定義しておく必要があります。今回は次のようなスキーマを、あらかじめ用意してあります。
    ので、ステータス200 (成功時) にはこのスキーマ定義に従ったデータを返却することを定義していることになります。

 

POST

ここではデータの作成を想定して、POSTのハンドラを定義しています。GETの時とは異なる点にフォーカスして見てみましょう。

  • consumes
    渡されるパラメータのMIMEタイプを指定します。今回はGETの時と違ってオブジェクトをサーバに渡すので、produces だけではなく、受け取る方のタイプ指定である consumes も定義しています。
  • in : “body”
    in はパラメータを埋め込む位置についての定義でした。その中の body は、リクエストボディにパラメータを設定することを指定します。
    in: “body” を指定した場合のみ、同ブロック内で schema を指定することができます。
    ここで使用しているスキーマは、GETのレスポンスで使用したものと同じものです。

PUT

ここではデータの更新のためにPUTなハンドラを定義しています。
ここからの2つは、GET/POST とはURLが違います。が、本質的な相違はありません。

  • in: path
    in はパラメータの位置の指定でした。path は、URLの一部として埋め込まれたパラメータについての定義です。
    今回の場合であれば、” /human/12345 ” と言ったリクエストにおける 12345 の部分に関する指定です。
    なお、 in: query は URL に付加されたパラメータの指定で、” /human?empNo=12345&code=1 ” などの使用を想定して定義でした。
  • in の併用
    見て分かるように、ここでは in: path と in: body が併用されています。このようにパラメータのタイプは混在させることができます。
    ここでは表現されているのは、「URLのパスの一部として empNo を受け取り、リクエストボディから info を受け取る」という定義です。

DELETE

特に目新しいことはないので、画像を貼るだけで説明は割愛します。

 

まとめ

  • 新しく RESTful API を作成するプロジェクトであれば、Swagger を使用することで、高いレベルでの開発メンバの意識統一や、一元化された仕様書の作成を行うことができる。
  • 学習コストはそれなりにあるが、基本文法を学ぶだけでも十分に構造化されたAPI定義書を作成することができる。

今回は単純なパラメータやスキーマしか触れなかったので、次回はもう少し複雑な定義方法についてまとめてみたいと思います。

以上です。ここまでご覧いただき、ありがとうございました!

参考

https://swagger.io/specification/v2/#pathItemParameters

https://news.mynavi.jp/itsearch/article/devsoft/2395

https://qiita.com/pi-su/items/4d9f142475a5be893beb

https://qiita.com/gcyata/items/342073fa7607fd4082bd

https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb

↓すごくおすすめ

Knowledgeカテゴリの最新記事