新しく作るAPIや、ドキュメントがない既存APIの仕様書を、OpenAPI(Swagger)形式で作るプロンプトです。リクエスト・レスポンスの形式だけでなく、エラー時の応答、認証、ページングなど、あとで揉めやすい部分まで設計します。
フロントエンドとバックエンドの認識合わせや、外部公開APIのドキュメント作成に使えます。
エンドポイントの要件から、OpenAPI形式の仕様書ドラフトとエラーレスポンス設計を作ります。
# ROLE
あなたはREST API設計のベストプラクティスに詳しいバックエンドエンジニアです。
# INPUT
- APIの目的:{例:社内の予約管理システムのAPI}
- 必要な操作:{例:予約の一覧取得・作成・更新・キャンセル}
- データ項目:{例:予約ID、日時、利用者ID、部屋ID、ステータス}
- 認証方式:{例:Bearerトークン}
- 既存のコードや仕様(あれば):
{ルーティングやコントローラのコード、既存ドキュメント}
# RULES
- OpenAPI 3.x のYAMLで出力する
- エラーレスポンスの形式を統一し、400/401/403/404/409/422/500 のうち必要なものを定義する
- 一覧取得にはページングと絞り込みのパラメータを設計する
- 入力にない仕様を決めた場合は、YAMLのコメントで「要確認」と書く
- 日時の形式、必須/任意、文字数などの制約を明記する
# OUTPUT
1. 設計方針のまとめ(URL設計、命名規則、エラー形式)
2. OpenAPI YAML
3. 要確認事項の一覧(仕様として決める必要があるもの)
新しく作るAPIや、ドキュメントがない既存APIの仕様書を、OpenAPI(Swagger)形式で作るプロンプトです。リクエスト・レスポンスの形式だけでなく、エラー時の応答、認証、ページングなど、あとで揉めやすい部分まで設計します。
フロントエンドとバックエンドの認識合わせや、外部公開APIのドキュメント作成に使えます。
APIで必要な操作とデータ項目を入力します。既存のコードがある場合は、ルーティングやコントローラ部分を貼ると実装に合った仕様書になります。
出力されたYAMLはSwagger Editorなどで読み込み、構文エラーがないか確認してから共有してください。
【入力】会議室予約API/操作:一覧・作成・更新・キャンセル/認証:Bearerトークン
【出力イメージ】
paths:
/reservations:
get:
summary: 予約一覧を取得
parameters:
- name: date_from
in: query
schema: { type: string, format: date }
…
要確認:同じ部屋・時間帯の重複予約は409を返すか、422を返すか