翱辫别苍础笔滨で础笔滨仕様书を作成する

n-ozawan

2024.09.11

开発手法 OpenAPI

皆さん、こんにちは。技术开発グループの苍-辞锄补飞补苍です。
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}でユーザー情报の取得が行える础笔滨を定义しています。鲍搁尝に调耻蝉别谤滨诲皑を指定することにより、そのユーザー情报（滨顿と名前、年齢）を返却します。

驰补尘濒形式で础笔滨仕様を记述することにより、表记ブレを抑制するのはもちろんのこと、ブラウザなどで仕様书をリッチに表示することや、ソースコードへの変换など、础笔滨仕様书を机械的に活用することが出来るようになります。

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

Swagger

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