Zenn
🦔

OpenAPIの基本

2024/09/04に公開
OpenAPI
tech

はじめに

このページでは、OpenAPIの記述例について詳細に解説します。

OpenAPIの詳細な記述例

OpenAPIの仕様は、APIの定義を機械可読形式で記述するための標準規格です。OpenAPIドキュメントは、APIのエンドポイント、リクエスト、レスポンス、セキュリティ情報、スキーマなどを詳細に定義することで、開発者やツールがAPIを理解しやすくします。以下では、OpenAPIの基本的な構造と各要素の具体例について詳しく見ていきます。

OpenAPIドキュメントの基本構造

OpenAPIドキュメントは主に以下のセクションで構成されます：

  • openapi: 使用するOpenAPIのバージョン（例: 3.0.0）。
  • info: APIの基本情報（タイトル、バージョン、ライセンス、連絡先など）。
  • servers: APIが提供されるサーバーのURL情報。
  • paths: APIの各エンドポイントとその操作（HTTPメソッドなど）を定義。
  • components: 再利用可能なデータモデルやセキュリティスキームなどのコンポーネントを定義。

具体例

以下に、ペットストアAPIのシンプルな例を示します。この例では、/petsというエンドポイントを提供し、GETリクエストでペットのリストを取得するAPIを定義しています。

openapi: 3.0.0  # 使用するOpenAPIのバージョン
info:
  title: ペットストアAPI  # APIのタイトル
  description: ペットストア情報を管理するためのAPI  # APIの説明
  version: 1.0.0  # APIのバージョン
  termsOfService: 'https://example.com/terms/'  # 利用規約のURL
  contact:  # APIの連絡先情報
    name: APIサポート
    url: 'https://www.example.com/support'
    email: '[email protected]'
  license:  # APIのライセンス情報
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'

servers:  # APIのサーバー情報
  - url: 'https://api.example.com/v1'

paths:  # APIのエンドポイントの定義
  /pets:
    get:  # GETリクエストの定義
      summary: すべてのペットを取得  # 要約
      description: ペットストアに登録されているすべてのペットを返します。  # 詳細説明
      responses:  # レスポンスの定義
        '200':  # HTTPステータスコード
          description: 正常に取得されました。  # レスポンスの説明
          content:
            application/json:  # レスポンスの内容タイプ
              schema:  # レスポンスボディのスキーマ定義
                type: array
                items:
                  type: object
                  properties:  # オブジェクトのプロパティ定義
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: "柴犬"
                    tag:
                      type: string
                      example: "犬"

この例では、/petsというエンドポイントに対してGETリクエストを行うと、ペットのリストがJSON形式で返されることがわかります。responsesフィールドには、APIが正常に動作した場合のHTTPステータスコード（200）とそのレスポンスの内容が定義されています。レスポンスのスキーマには、id、name、tagというプロパティが含まれ、各プロパティの型と例も示されています。

より詳細な要素の解説

1. Infoオブジェクト

infoオブジェクトはAPIの基本情報を提供します。このオブジェクトにはtitle、version、description、termsOfService、contact、licenseなどが含まれます。これらの情報は、APIのメタデータとしてユーザーに提供されます。

2. Pathsオブジェクト

pathsオブジェクトは、APIの各エンドポイントを定義する中心的なセクションです。ここでは、エンドポイントごとのHTTPメソッド（GET, POST, PUT, DELETEなど）、リクエストパラメータ、リクエストボディ、レスポンス、セキュリティスキームなどを定義します。

3. Componentsオブジェクト

componentsオブジェクトは、APIで使用される再利用可能なオブジェクトを定義します。例えば、共通のエラーレスポンス、データモデル、セキュリティスキームなどを定義し、$ref参照を使って他の部分で使用できます。

4. Serversオブジェクト

serversオブジェクトは、APIがデプロイされるサーバーのURLを定義します。このフィールドには、開発、テスト、本番など複数のサーバーURLを指定することができます。

OpenAPIのベストプラクティス

OpenAPIを使用する際のベストプラクティスとして、以下の点に注意することが推奨されます：

  • バージョン管理: OpenAPIドキュメントはバージョン管理システムで管理し、変更履歴を明確にする。
  • 詳細なコメントと説明: 各エンドポイントやパラメータには詳細な説明を記述し、APIの使い方を明確にする。
  • 再利用可能なコンポーネントの活用: componentsオブジェクトを活用して、再利用可能なデータ構造やスキーマを定義し、コードの重複を避ける。
  • セキュリティ対策: セキュリティスキームを明確に定義し、APIのセキュリティを強化する。

まとめ

OpenAPIは、APIの設計と開発を効率化するための強力なツールです。詳細な仕様を持つことで、ドキュメント生成、コード生成、テスト、セキュリティ分析などのプロセスを自動化し、APIの一貫性と品質を確保することができます。より詳しい情報は公式ドキュメントを参照してください：OpenAPI Documentation【8†source】。

Discussion