API仕様を簡単に作成&管理しよう!

こんにちは!ドイです。

API仕様をまとめるときに、どんなツールを使っていますか?ExcelやGoogleスプレッドシートで管理したり。。。
色々だと思いますが、今回はOpenAPIについてまとめていきたいと思います。

OpenAPIとは

swagger.io

「OpenAPI仕様(旧Swagger仕様)は、REST APIのためのAPI記述形式である」と説明があります。
記述方式は、YAML形式やJSON形式で、利用可能なエンドポイントや認証方法などを記述することができます。ExcelやGoogleスプレッドシートで管理すると、以下の点が難点になるかと思います。

  • API仕様を書く人によって、フォーマットが異なる
  • 変更を管理するのが難しい
  • バージョン管理が難しい

こんな問題点を楽に解決してくれるのが、OpenAPIです。

OpenAPI Editor

API仕様をPhpStorm上で記述するためのプラグインを入れたいと思います。

editor.swagger.io

見ていただくと分かるとおり、記述したAPI仕様がエンドポイントごとに分類され表示されます。クリックすることで、該当のコードの箇所に飛んでくれるので編集の際に便利です。

  1. PhpStormのPreferencesを開く
  2. メニュー一覧からプラグインを選択
  3. OpenAPI(Swagger)Editorと入力して検索
  4. 該当のプラグインをインストール

記述方法

YAML形式で記述していこうと思います。

OpenAPIのバージョン
Open APIのバージョンを記述します。

openapi: "3.0.2"

APIについての情報を記述します

servers:
  - url: https://www.hogehoge.jp/api/
# パス
paths:
  # エンドポイント
  /getUser:
    # HTTPメソッド
    get:
      # エンドポイントの説明
      tags:
        - "ユーザー一覧"
      # API名
      operationId: getUser
      # APIの説明
      summary: "ユーザーの取得"
      # 引数の設定
      parameters:
        - $ref: "#/components/parameters/id"
      # 返却値
      responses:
        200:
          # 返却値の説明
          description: "成功しました"
          # ヘッダー情報
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/responses/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  user:
                    # 返却する形式
                    type: array
                    items:
                      type: object
                      # カラム情報
                      properties:
                        no:
                          type: "integer"
                          format: "int"
                          example: "1"
                          description: "no"
                        name:
                          type: "string"
                          example: "doi"
                          description: "ユーザー名"
                        email:
                          type: "string"
                          example: "XXXXXX@xxx.xxxxxx"
                          description: "メールアドレス"
                        birthday:
                          type: "string"
                          example: "1991/10/10"
                          description: "誕生日"

parametersやheadersに、他の部分とは違う記述があるので、こちらについて説明します。

参照

複数のAPIを管理する中で、APIごとに同じ記述をする必要が出てきます。上記のように、ヘッダー情報やパラメーターは共通になってくるかと思います。その場合に、毎回同じ記述をする手間を省くために参照場所を記述します。

$ref: "#/components/parameters/id"

$refの後ろに、参照したいパスを記述します。参照部分は、下記のように定義します。

components:
  parameters:
    id:
      in: header
      name:xxxxx
      schema:
        type: string
        example: "1"
      required: true
  responses:
    headers:
      X-RateLimit-Limit:
        description: "1分あたりのリクエスト可能数"
        schema:
          type: "integer"

データ型

propertiesのformatでデータ型を記述しています。OpenAPIで設定できるデータ型は下記になります。

  • integer(整数 )
  • number(浮動小数点数)
  • string(文字列)
  • boolean(真偽値)
  • array(配列)
  • object(オブジェクト))

よく使用するDate型がないので、日付を扱う際はstringとして使用します。

ここまででAPI仕様は一定のフォーマットで記述できたかと思います。

先ほど紹介したプラグインを入れた場合、右上にエディター表示のボタンが表示されているのでクリックしてください。ParametersとResponsesに分かれて、記述した内容が表示されます。

まとめ

OpenAPIを使用することで、簡単にAPI仕様を記述することができました。管理しやすく、API実装の際のミスの軽減にもつながると思います。他にも活用できていないツールがあるので、今後も上手に活用していきたいと思います。