MENU

OpenAPI 3.1.0 YAMLの基本構造

以下に、OpenAPI 3.1.0 YAMLファイルの文法と構造を解説します。

OpenAPI 3.1.0 YAMLの基本構造

OpenAPI 3.1.0は、OpenAPI 3.0.0の機能を拡張し、JSON Schemaの完全な互換性などの新機能を追加しています。以下に基本的な構造を示します。

openapi: 3.1.0
info:
  title: APIのタイトル
  description: APIの詳細な説明
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 本番サーバ
paths:
  /users:
    get:
      summary: すべてのユーザーを取得
      responses:
        '200':
          description: 成功レスポンス
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

各セクションの説明

1. openapi

OpenAPIのバージョンを指定します。この例では3.1.0です。

2. info

APIに関する基本情報を提供します。

  • title: APIの名前
  • description: APIの説明
  • version: APIのバージョン

3. servers

APIが利用可能なサーバのリストを指定します。

  • url: サーバのURL
  • description: サーバの説明

4. paths

APIの各エンドポイントとそのメソッドを定義します。

  • /users: エンドポイントのパス
  • get: HTTPメソッド
    • summary: エンドポイントの概要
    • responses: レスポンスの詳細
    • '200': ステータスコード
      • description: レスポンスの説明
      • content: レスポンスの内容と形式
      • application/json: レスポンスのコンテンツタイプ
        • schema: レスポンスデータのスキーマ
        • type: データの型（この場合は配列）
        • items: 配列の各要素のスキーマ参照

5. components

スキーマやセキュリティスキームなどの再利用可能なコンポーネントを定義します。

  • schemas: スキーマの定義
  • User: スキーマ名
    • type: オブジェクトの型
    • properties: プロパティのリスト
    • id: プロパティ名
      • type: プロパティの型（この場合は整数）
    • name: プロパティ名
      • type: プロパティの型（この場合は文字列）
    • email: プロパティ名
      • type: プロパティの型（この場合は文字列）

OpenAPI 3.1.0の新機能

  1. JSON Schema 2020-12の完全なサポート:
    OpenAPI 3.1.0は、JSON Schema 2020-12の完全なサポートを提供します。これにより、スキーマ定義の柔軟性と表現力が向上します。
  2. webhooks:
    Webhookのサポートが追加され、サーバーからクライアントに対するコールバックを定義できるようになりました。
  3. リファレンス解決:
    $refを使用して、JSON Schemaと同様に外部ファイルへの参照をより柔軟に行うことができます。

例: ユーザー作成エンドポイントの追加（OpenAPI 3.1.0）

以下は、新しいユーザーを作成するためのPOST /usersエンドポイントを追加する例です。

openapi: 3.1.0
info:
  title: Sample API
  description: APIの詳細な説明
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 本番サーバ
paths:
  /users:
    post:
      summary: 新しいユーザーを作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: ユーザー作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

このエンドポイントは、新しいユーザーのデータを受け取り、それをもとにユーザーを作成します。リクエストボディとレスポンスのスキーマは、先に定義されたUserスキーマを参照しています。

このように、OpenAPI 3.1.0 YAMLファイルを使ってAPIの設計とドキュメントを詳細に記述できます。これにより、APIの構造や動作を明確に伝えることができます。

コラム