ドキュメント

仕組み

OpenAPIは、HTTP APIの仕様を機械可読な形式で記述する規格です。

Swaggerは、Swagger UIやSwagger Editorなど、OpenAPIを扱うツール群の名称として使われています。OpenAPI仕様、SwaggerとOpenAPIの関係

記述の例

openapi: 3.0.3
info:
  title: Articles API
  version: 1.0.0

paths:
  /articles/{id}:
    get:
      summary: 記事を取得する
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 取得成功
          content:
            application/json:
              schema:
                type: object
                required: [id, title]
                properties:
                  id:
                    type: integer
                  title:
                    type: string
        "404":
          description: 記事が存在しない

これは簡略化した例ですが、URL、パラメーター、成功レスポンス、エラーを同じ形式で表現できます。

何に役立つのか

同じ仕様から、次の作業へつなげられます。

• 閲覧用ドキュメントの生成。
• クライアントコードや型の生成。
• モックサーバーの作成。
• 実際のレスポンスと仕様の整合性確認。
• 変更による互換性への影響の確認。

フロントエンドとバックエンドが別々に開発する場合、口頭の説明だけに依存しにくくなります。

型だけでは足りない

たとえば「文字列」と書くだけでは、次は分かりません。

日時のタイムゾーンは何か
空文字を許可するか
省略とnullは同じか
一覧の並び順は何か
カーソルはいつまで使えるか
再送時に重複実行されるか

これらの意味や動作も、説明や例として記述する必要があります。

「オプションではない」は仕様上の義務ではない

OpenAPIは、HTTP APIを作るうえでの必須要件ではありません。

元の表現は、「実務でAPI契約の明文化を軽視しない」という助言として読むのが適切です。採用する形式以上に重要なのは、実装と仕様が一致し、利用者が必要な情報を得られることです。

自動生成されたドキュメントでも、正常系しか載っていなければ、再試行やエラー処理の設計には足りません。

設計上の要点
ドキュメントの存在ではなく、クライアントが迷わず実装できる契約になっているかを確認します。