M
API仕様書を効率的に作成・編集する
by mktkhr
分割構成のOpenAPI仕様書を一貫性を保ったまま拡張：paths、schemas、parametersを別々のYAMLファイルに管理しながら、参照（$ref）により統一されたAPI仕様を構築できます。 新しいエンドポイントを規約に従って追加：テンプレートに従うだけで、日本語の説明、適切なレスポンス形式、エラーハンドリング定義までが自動で揃います。 スキーマと実装コードの乖離を防ぐ：OpenAPI定義が真実の情報源となるため、仕様書と実装の齟齬が生じません。 data/errorsラッパーでレスポンス形式を統一：すべてのAPIレスポンス（/healthを除く）が共通の構造を持つことで、クライアント実装が単純化されます。 自動コード生成で実装工数を削減：make api-generateで、OpenAPI仕様からサーバーコード・クライアント型定義が自動生成されます。 REST APIの新しいエンドポイントを追加するが、仕様書作成の手順を確認したい開発者 OpenAPI仕様書をプロジェクト内で標準化し、チーム全体の一貫性を保ちたい人 スキーマ設計の初期段階で「こうやって書くのが正解」という具体例が欲しい初心者 既存API仕様の拡張時に、破壊的な変更を回避する手法を学びたい人 プロジェクトはapi/以下に分割構成のOpenAPI仕様書を使用します。構成はapi/openapi.yaml（ルート、$ref参照のみ）、api/paths/（エンドポイント定義）、api/components/schemas/（スキーマ定義）、api/components/parameters/、api/components/responses/です。 必須ルール：①すべてのAPIレスポンス（/healthを除く）はdata/errorsラッパー形式で、dataとerrorsプロパティを持ちます。②すべてのdescriptionは日本語で記載します。③参照パスはschemas間は./filename.yaml#/SchemaName、pathsからの参照は../components/schemas/filename.yaml#/SchemaName、responsesへは../components/responses/errors.yaml#/ErrorTypeです。 作業手順は、エンドポイント追加時は①api/paths/.yamlを作成・編集②必要なスキーマをapi/components/schemas/.yamlに追加③api/openapi.yamlに$ref参照を追加④make api-generateでコード生成、スキーマ追加時は適切なapi/components/schemas/*.yamlに定義を追加しData型とResponse型の両方を作成、パラメータ追加時は共通パラメータをapi/components/parameters/common.yamlに追加して$refで参照します。