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

こんにちは！ドイです。

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

OpenAPIとは

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

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

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

OpenAPI Editor

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

editor.swagger.io

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

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

記述方法

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"