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

Web エンジニアなら知っておきたい

インフラ担当の柴田です。「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は文字列型ということは分かりますが、何文字まで許されるのかが利用者に分からないため利用時に問題になります。

まとめ

APIのインタフェース定義は、チームで開発するうえで重要なドキュメントになります。OASは広く利用されている記述方法になるため是非書き方や読み方を学んでください。

*1:以前はSwagger Specificationと呼ばれていました

*2:様々なサードパーティー製ツールが存在していることからも人気がうかがえます https://openapi.tools/