openapi

OpenAPI Specification

このスキルでは、OpenAPI Specification（OAS）ドキュメントの操作方法について説明します。

現行バージョン： OpenAPI 3.2.0（2025年9月）

クイックナビゲーション

• ドキュメント構造：references/document-structure.md
• オペレーションとパス：references/operations.md
• スキーマとデータ型：references/schemas.md
• パラメーターとシリアライズ：references/parameters.md
• セキュリティ：references/security.md

使用する場面

• 新しい OpenAPI 仕様ドキュメントを作成する
• HTTP API エンドポイントを記述する
• リクエスト／レスポンスのスキーマを定義する
• API セキュリティ（OAuth2、API キー、JWT）を設定する
• 既存の OpenAPI ドキュメントを検証する
• 仕様からクライアント／サーバーコードを生成する

ドキュメント構造の概要

OpenAPI ドキュメントのルートには、OpenAPI Object または Schema Object のいずれかが必ず必要です。

必須フィールド

openapi: 3.2.0 # REQUIRED: OAS version
info: # REQUIRED: API metadata
  title: My API
  version: 1.0.0

完全な構造

openapi: 3.2.0
info:
  title: Example API
  version: 1.0.0
  description: API description (supports CommonMark)
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get:
      summary: List resources
      responses:
        "200":
          description: Success
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}
security:
  - apiKey: []
tags:
  - name: resources
    description: Resource operations

コアオブジェクトのリファレンス

Info Object

info:
  title: Example API # REQUIRED
  version: 1.0.0 # REQUIRED (API version, NOT OAS version)
  summary: Short summary
  description: Full description (CommonMark)
  termsOfService: https://example.com/terms
  contact:
    name: API Support
    url: https://example.com/support
    email: [email protected]
  license:
    name: Apache 2.0
    identifier: Apache-2.0 # OR url (mutually exclusive)

Server Object

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://{environment}.example.com:{port}/v1
    description: Configurable
    variables:
      environment:
        default: api
        enum: [api, staging, dev]
      port:
        default: "443"

Path Item Object

/users/{id}:
  summary: User operations
  parameters:
    - $ref: "#/components/parameters/userId"
  get:
    operationId: getUser
    responses:
      "200":
        description: User found
  put:
    operationId: updateUser
    requestBody:
      $ref: "#/components/requestBodies/UserUpdate"
    responses:
      "200":
        description: User updated

Operation Object

get:
  tags: [users]
  summary: Get user by ID
  description: Returns a single user
  operationId: getUserById # MUST be unique across all operations
  parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    "200":
      description: Success
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"
    "404":
      description: Not found
  security:
    - bearerAuth: []
  deprecated: false

スキーマのレシピ

基本オブジェクト

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        age:
          type: integer
          minimum: 0

allOf による合成

ExtendedUser:
  allOf:
    - $ref: "#/components/schemas/User"
    - type: object
      properties:
        role:
          type: string
          enum: [admin, user, guest]

oneOf によるポリモーフィズム

Pet:
  oneOf:
    - $ref: "#/components/schemas/Cat"
    - $ref: "#/components/schemas/Dog"
  discriminator:
    propertyName: petType
    mapping:
      cat: "#/components/schemas/Cat"
      dog: "#/components/schemas/Dog"

null 許容と省略可能

# OAS 3.1+ uses JSON Schema type arrays
properties:
  nickname:
    type: [string, "null"] # nullable

パラメーターの場所

場所	in 値	備考
パス	path	必ず required: true にすること
クエリ	query	標準的なクエリパラメーター
クエリ文字列	querystring	クエリ文字列全体を単一のパラメーターとして扱う
ヘッダー	header	名前の大文字と小文字を区別しない
Cookie	cookie	Cookie の値

パラメータースタイル

スタイル	in	型	例（color=blue,black）
simple	path	配列	blue,black
form	query	プリミティブ／配列／オブジェクト	color=blue,black
matrix	path	プリミティブ／配列／オブジェクト	;color=blue,black
label	path	プリミティブ／配列／オブジェクト	.blue.black
deepObject	query	オブジェクト	color[R]=100&color[G]=200

セキュリティスキーム

API キー

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header # header, query, or cookie
      name: X-API-Key

Bearer トークン（JWT）

bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT

OAuth2

oauth2:
  type: oauth2
  flows:
    authorizationCode:
      authorizationUrl: https://auth.example.com/authorize
      tokenUrl: https://auth.example.com/token
      scopes:
        read:users: Read user data
        write:users: Modify user data

セキュリティの適用

# Global (all operations)
security:
  - bearerAuth: []

# Per-operation
paths:
  /public:
    get:
      security: [] # Override: no auth required
  /protected:
    get:
      security:
        - oauth2: [read:users]

Reference Object

重複を避けるには $ref を使用します。

# Reference within same document
$ref: '#/components/schemas/User'

# Reference to external file
$ref: './schemas/user.yaml'
$ref: './common.yaml#/components/schemas/Error'

Components Object

再利用可能な構成要素：

components:
  schemas: # Data models
  responses: # Reusable responses
  parameters: # Reusable parameters
  examples: # Reusable examples
  requestBodies: # Reusable request bodies
  headers: # Reusable headers
  securitySchemes: # Security definitions
  links: # Links between operations
  callbacks: # Webhook definitions
  pathItems: # Reusable path items

ベストプラクティスのチェックリスト

• すべてのオペレーションに operationId を含める（一意で、プログラミングに適したもの）
• 再利用可能なコンポーネントには $ref を使用する
• 意味のある description フィールドを追加する（CommonMark に対応）
• 考えられるすべてのレスポンスコードを定義する
• 複雑なスキーマには examples を含める
• 関連するオペレーションをグループ化するには tags を使用する
• 非推奨のオペレーションには deprecated: true を設定する
• info.version にはセマンティックバージョニングを使用する

重大な禁止事項

• openapi フィールドと info フィールドを省略しないでください（これらは必須です）
• 重複する operationId の値を使用しないでください
• Reference Object で $ref と兄弟プロパティを併用しないでください
• required: true を指定せずにパスパラメーターを使用しないでください
• 新しい API で暗黙的な OAuth2 フローを使用しないでください（非推奨です）
• 保護されたエンドポイントにセキュリティを設定し忘れないでください

検証

ファイル名

• エントリードキュメント：openapi.json または openapi.yaml（推奨）
• 形式：JSON または YAML（同等）
• すべてのフィールド名では大文字と小文字が区別されます

よくある検証エラー

エラー	修正方法
必須フィールドがありません	openapi、info.title、info.version を追加します
operationId が無効です	一意で有効な識別子を使用します
パスパラメーターがパスにありません	{param} がパラメーター名と一致していることを確認します
パステンプレートが重複しています	競合する /users/{id} と /users/{userId} を削除します
$ref が無効です	URI の構文と参照先の存在を確認します

リンク

• ドキュメント
• リリース
• GitHub
• 学習ポータル