Webエンジニアなら知っておきたいOpenAPI Specificationの基礎

インフラ担当の柴田です。「Web エンジニアなら知っておきたい」ということで、今日はOpenAPI Specification の主要な構成要素、データ型、制約について紹介します。

OpenAPI Specificationとは？

OpenAPI Specification（OAS）*1は、HTTP APIのインタフェースを定義するための仕様で広く採用されています*2。OASに則ってAPIのインタフェースを記述することにより、人間とコンピュータ双方がAPIの利用方法を理解できます。現在はOpenAPI Initiativeという組織で管理、推進されています。

OpenAPI Document

OASに則って定義されたAPIの仕様書は、OpenAPI Documentと呼ばれています。OpenAPI DocumentはYAMLまたはJSON形式で記述されます。

OpenAPI Documentの主要な構成要素

OpenAPI Documentは、APIの要素を定義するいくつかのフィールドから成り立っています。主要なフィールドとしては以下のものがあります。

openapi: OASのバージョンを記述します
iInfo: APIの基本情報を記述します（タイトル、バージョンなど）
servers: APIがホストされているサーバーのURLを記述します
paths: インタフェース定義のメイン部分です。APIが提供するエンドポイントやリクエスト時のHTTPメソッド（GET、POSTなど）、レスポンスの定義などを記述します
components: リクエストやレスポンスで使われるデータ構造を記述します

データ型と制約

OASでは、APIでやり取りされるデータの型typeを使い定義します。以下のデータ型が利用できます。データ型はformatを用いることでより詳細な情報を提供できます。

データ型の例

type	説明
integer	整数
number	浮動小数点数含む数値
string	文字列
boolean	真偽値
array	配列
object	キーと値のペアからなるオブジェクト

format の例

type	format	説明
integer	int32	符号付き32ビット整数
integer	int64	符号付き64ビット整数
number	float	浮動小数点数
number	double	倍精度の浮動小数点数
string	password	入力をマスクするためのUIへのヒント

データ型には以下のようなValidation Keywordsを追加できます。Validationの情報を使うことで値の制約を定義することができます。

Validation Keywords

Validation	説明
minimum	数値の最小値
maximum	数値の最大値
minLength	文字列の最小長
maxLength	文字列の最大長
pattern	文字列が満たすべき正規表現パターン

APIの定義例

https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yamlより一部抜粋

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            maximum: 100
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      maxItems: 100
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

この例は、OpenAPI Initiativeが公開しているサンプルのOpenAPI Documentでペットのリストを取得するためのAPIエンドポイント/petsを定義しています。 /petsにGETリクエストを送ると、ペットオブジェクトの配列が返ることが分かります。さらに、ペットオブジェクトは、id（整数型）とname（文字列型）とtag（文字列型）のプロパティを持ち、idとnameは必須のパラメータということが分かります。

パラメータには前述のようにValidation Keywordsでどのような値が受け入れられるのかを記述が可能です。APIのパラメータにはできる限りValidation Keywordsを定義するようにしてください。例のOpenAPI Documentではnameは文字列型ということは分かりますが、何文字まで許されるのかが利用者に分からないため利用時に問題になります。