Goalist Developers Blog

Swaggerを使ってRestful APIを記述する

API Gateway AWS

こんにちは、ゴーリストのトゥアンです。

ウェブ開発でRestful APIはだんだん普及していると共に、Resful APIを記述するためにいろいろな仕方があります。

Swaggerを使うことは下記の通りに、いくつかの利点があります。

  • Amazon API Gatewayへ展開できる
  • フロントエンド開発のため、モックサーバーを作りやすい
  • OpenAPI仕様の基準に基づくAPIの入力（リクエスト）・出力(レスポンス)を定義できる

Swagger 3.0 は2017年07月にリリースされましたが、現在AWSはSwagger 2.0だけサポートしているので、今回の記事でSwagger 2.0について説明します。

Swaggerファイルのフォーマット

SwaggerでサポートしているフォーマットはYAMLとJSONです。

Swaggerファイルの構造は複数階層のオブジェクトです。ルートオブジェクトは「Swagger」というオブジェクトです。

1. Swagger オブジェクト

詳しい情報は下記のリンクにご参考ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object

大切なフィールドは:

フィールド名 タイプ 説明
swagger String 必須です。"2.0"という固定な価値があります。
info Object 必須です。情報のオブジェクトです。後で説明します。
host String ホスト名又はホストのIPアドレスです。
basePath String 全部APIの共有なパスです
schemes String 全部APIのプロトコル(httpやhttps, ws, wssなど)です
paths Object 必須です。
全部APIを一つずつ記述するためのオブジェクトです。
後で説明します。
definitions Object 自由なオブジェクトを定義できます。後で説明します。

2. info オブジェクト

APIについてのメタデータです。 詳しい情報は下記のリンクにご参考ください。 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object

大切なフィールドは:

フィールド名 タイプ 説明
title String 必須です。アプリケーションのタイトルです
version String 必須です。API記述仕様書のバーションです。

3. paths オブジェクト

APIの記述情報です。 詳しい情報は下記のリンクにご参考ください。 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#paths-object

大切なフィールドは:

フィールド名 タイプ 説明
/{path}
{path}は任意に定義できる		 Object 定義されたpathに該当するAPIの記述です。
「Path Item」 というオブジェクトです。
後で説明します。

Path Itemオブジェクトの詳しい情報は下記のリンクにご参考ください。 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#paths-item-object

大切なフィールドは:

フィールド名 タイプ 説明
get Object 定義されたpathに該当するGETメソードの記述です。
「Operation」というオブジェクトです。後で説明します。
put Object pathに該当するPUTメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
post Object pathに該当するPOSTメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
delete Object 定義されたpathに該当するDELETEメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
options Object pathに該当するOPTIONSメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
head Object pathに該当するHEADメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
patch Object pathに該当するPATCHメソードの記述です。
タイプはgetのOperationオブジェクトと同じです。
parameters Array 全部のメソッドの共有なリクエストパラメーターです。
配列要素のタイプは以下のいずれかです。
・definitionsに自由に定義したオブジェクトに参考
・「Parameter」というオブジェクト。後で説明します。

4. operation オブジェクト

定義されたパスの一つのメソッドのリクエスト・レスポンスの記述です。
詳しい情報は下記のリンクにご参考ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object

大切なフィールドは:

フィールド名 タイプ 説明
parameters Array メソードのリクエストパラメーターです。
配列要素のタイプは以下のいずれかです。
・definitionsに自由に定義したオブジェクトに参考
・「Parameter」というオブジェクト
responses Object レスポンスを記述するためのオブジェクトです。
後で説明します。

5. parameter オブジェクト

リクエストパラメーターの記述です。
詳しい情報は下記のリンクにご参考ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object

大切なフィールドは:

フィールド名 タイプ 説明
name String 必須です。パラメーターの名前です。
in String 必須です。リクエストにパラメーターを含める場所です。
価値は以下のいずれかです。
・"query"
・"header"
・"path"
・"formData"
・"body"
required Boolean 定義されたパラメーターは必須かどうか記述です。

6. responses オブジェクト

APIレスポンスの記述です。 詳しい情報は下記のリンクにご参考ください。 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responses-object

大切なフィールドは:

フィールド名 タイプ 説明
{HTTP ステータスコード}
(400や404, 500など)		 Object 定義されたHTTPステータスコードに該当するレスポンスの記述です。
タイプは以下のいずれかです。
・definitionsに自由に定義したオブジェクトに参考　
・「Response」 というオブジェクトです。後で説明します。

Responseオブジェクトの詳しい情報は下記のリンクにご参考ください。 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject

大切なフィールドは:

フィールド名 タイプ 説明
description String 必須です。レスポンスの概念記述です。
schema Object APIレスポンスの構造詳細記述です。後で説明します。

7. definitions オブジェクト

自由なオベジェクトの定義です。
詳しい情報は下記のリンクにご参考ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitionsObject

definitions オブジェクトのフィールドは:

フィールド名 タイプ 説明
{name}
name: 定義したいオベジェクトの名前です。		 Object 指定されたnameがあるオブジェクトの記述です。
タイプはresponseのschemaオブジェクトと同じです。
後で説明します。

SchemaオブジェクトはJSON Schema仕様書に基づいて定義されます。
JSON Schema仕様書は下記のリンクにご参考ください。
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitionsObject　
また、JSON Schema仕様書の他にSwaggerのSchemaオブジェクトは特別なフィールドもあります。
詳しい情報は下記のリンクにご参考ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schema-object

大切なフィールドは:

フィールド名 タイプ 説明
type String 定義したいオブジェクトのタイプです。
サポートしているタイプは:
原始タイプ（"integer"や"string"など)、
"array"と"object"です

typeが"array"である場合、下記のフィルードがあります。

フィールド名 タイプ 説明
items Object 配列要素を定義するためのSchemaオブジェクトです。

typeが"object"である場合、下記のフィルードがあります。

フィールド名 タイプ 説明
required Array 必須なフィルード名の配列です。
properties Object オブジェクトのフィルードを定義するための各Schema オブジェクトです。

サンプル

課題：https://example.swagger.io/v1/users/{user_id} パスのGETメソッドとPUTメソッドを記述します。

GETメソッド：
リクエストのパラーメータ:
+ user_id : パスにある
レスポンスのオブジェクト：ユーザの名前とユーザのメールアドレス

PUTメソッド：
リクエストのパラーメータ:
+ user_id : パスにある
+ name: ボディにある
+ email: ボディにある
レスポンスのオブジェクト：成功な場合に200コードを返却して、失敗な場合に400コードと404コードを返却します。

上記のAPIを記述するために、下記のSwaggerファイルを作ります。

swagger: "2.0"
info: # infoオブジェクト
  title: "Swaggerの例"
  version: "1.0.0"
host: "example.swagger.io"
basePath: "/v1"
schemes:
- "https"
paths: # pathsオブジェクト
  /user/{user_id}:
    get: # getメソッドのoperationオブジェクト
      tags:
      - "userAPI"
      summary: "ユーザーIDによって、ユーザー情報を取得する"
      operationId: "getUserByUserId"
      produces:
      - "application/json"
      parameters: # parameterオブジェクトの配列
      - name: "user_id"
        in: "path"
        description: "ユーザーID"
        required: true
        type: "number"
      responses: # responsesオブジェクト
        200:
          description: "成功なレスポンス"
          schema: # schemaオブジェクト
            $ref: "#/definitions/User" 
            # definitionsに定義されたオブジェクトの参考
        400:
          description: "無効なユーザーID"
        404:
          description: "ユーザーを見つけていません"
    put: # putメソッドのoperationオブジェクト
      tags:
      - "userAPI"
      summary: "ユーザーIDによって、ユーザー情報を更新する"
      operationId: "updateUserByUserId"
      produces:
      - "application/json"
      parameters: # parameterオブジェクトの配列
      - name: "user_id"
        in: "path"
        description: "ユーザーID"
        required: true
        type: "number"
      - in: "body"
        name: "body"
        required: true
        schema: # schemaオブジェクト
          $ref: "#/definitions/UpdateUserReq" 
          # definitionsに定義されたオベジェクの参考
      responses: # responsesオブジェクト
        200:
          description: "成功なレスポンス"
        400:
          description: "無効なユーザーID"
        404:
          description: "ユーザーを見つけていません"
definitions: # definitionsオブジェクト
  User: # schemaオブジェクト
    type: "object"
    properties:
      id: # schemaオブジェクト
        type: "integer"
        format: "int64"
      name: # schemaオブジェクト
        type: "string"
      email: # schemaオブジェクト
        type: "string"
  UpdateUserReq: # schemaオブジェクト
    type: "object"
    required:
      - "name"
      - "email"
    properties:
      name: # schemaオブジェクト
        type: "string"
      email: # schemaオブジェクト
        type: "string"

「Swagger UI」を使って、記述したAPIは綺麗に表示できます。

API概要の表示 f:id:t-nguyen:20180709155906p:plain GETメソッドの表示 f:id:t-nguyen:20180709154630p:plain PUTメソッドの表示 f:id:t-nguyen:20180709154752p:plain

ツール

Swaggerを書くために、「Swagger Editor」を使って、エラーがある場合、すぐ報告は出ます。

Swaggerファイルを作成した後で、「Swagger UI」を使って、記述したAPIは綺麗に表示できます。

この二つのツールをローカル環境にダウンロードすることと、ウェブブラウザーにオンラインで使うことと、どちらもできます。

参考書類

今回の記事でSwagger 2.0について少し説明しました。
詳しい情報は下記のリンクにご参考ください。

バーション2.0 : https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
バーション3.0 : https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md