OpenAPIでAPI仕様書を作成する

n-ozawan

2024.09.11

開発手法 OpenAPI

皆さん、こんにちは。技術開発グループのn-ozawanです。
2008年に粘菌が迷路の最適解を導き出すという研究がイグノーベル賞を受賞しました。ここ最近ではエリンギの真菌がロボットを動かすようになったとか。菌って不思議ですね。

本題です。
皆さんはAPI仕様書を何で書いていますか？ここで言うAPIとは、HTTP APIを指します。WordやExcelなどのOffice製品で記述しているプロジェクトも健在だと思います。今回は、Yaml形式でAPI仕様書を記述するOpenAPIについてお話しします。

OpenAPI

概要

OpenAPIは、HTTP APIをYaml形式で記述するための標準仕様です。例えばユーザー情報を取得するAPIであれば以下のように記述します。

paths:
  /api/user/{userId}:
    get: 
      operationId: getUserInfo
      summary: ユーザー情報取得
      description: ユーザー情報を取得する
      parameters: 
        - name: userId
          in: path
          description: ユーザーID
          required: true
          schema: 
            type: string
      responses: 
        '200': 
          description: 成功
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  userId:
                    description: ユーザーID
                    type: string
                  name:
                    description: ユーザー名
                    type: string
                  age:
                    description: 年齢
                    type: number
        '404':
          description: Not Found.

少々長いですが、簡単に説明すると、GET /api/user/{userId}でユーザー情報の取得が行えるAPIを定義しています。URLに{userId}を指定することにより、そのユーザー情報（IDと名前、年齢）を返却します。

Yaml形式でAPI仕様を記述することにより、表記ブレを抑制するのはもちろんのこと、ブラウザなどで仕様書をリッチに表示することや、ソースコードへの変換など、API仕様書を機械的に活用することが出来るようになります。

元々はSwaggerという名前で策定された仕様でしたが、SwaggerがOpenAPI Initiativeへ寄贈することにより、OpenAPIという名前となり標準化されました。

Swagger

元々Swaggerで使われていた仕様がOpenAPIとして標準化されたことから、Swagger = OpenAPIと思われるかもしれません。OpenAPI Initiativeへ寄贈したのは「Yaml形式による記述仕様」であり、今現在のSwaggerはOpenAPIを利用したツール類となっています。