【API】Swagger (OpenAPI 3.0) チートシート - j-komatsu/myCheatSheet GitHub Wiki
Swagger (OpenAPI 3.0) チートシート
このチートシートは、YAML形式でOpenAPI仕様を記述する際の実践的なガイドを提供します。Swagger Editorでコピペして確認可能なサンプルを含んでいます。
1. 基本構造
API仕様の基盤となる構造を定義します。APIのバージョン、メタデータ、サーバー情報などを設定します。
openapi: 3.0.0
info:
title: サンプルREST API
version: 1.0.0
description: Swaggerドキュメントを用いたサンプルREST API
servers:
- url: https://api.example.com/v1
description: 本番環境
- url: https://staging.example.com/v1
description: ステージング環境
paths:
/users:
get:
summary: ユーザー一覧を取得
description: 全てのユーザー情報を取得します
responses:
'200':
description: 正常なレスポンス
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
2. パス（Paths）の定義
パスはAPIエンドポイントを表します。それぞれのエンドポイントにはHTTPメソッドとレスポンスを定義します。
GETの例
リソースを取得します。
paths:
/users:
get:
summary: ユーザー一覧を取得
description: 全てのユーザー情報を取得します
responses:
'200':
description: 正常なレスポンス
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
POSTの例
新しいリソースを作成します。
paths:
/users:
post:
summary: 新しいユーザーを作成
description: データベースにユーザーを追加します
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'201':
description: ユーザーが正常に作成されました
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
DELETEの例
リソースを削除します。
paths:
/users/{userId}:
delete:
summary: ユーザーを削除
description: ユーザーIDを指定してユーザーを削除します
parameters:
- in: path
name: userId
required: true
schema:
type: integer
description: 削除するユーザーのID
responses:
'204':
description: ユーザーが正常に削除されました
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
PUTの例
リソース全体を更新します。
paths:
/users/{userId}:
put:
summary: ユーザー情報を更新
description: ユーザーの情報を全て更新します
parameters:
- in: path
name: userId
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: ユーザーが正常に更新されました
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
PATCHの例
リソースの一部を更新します。
paths:
/users/{userId}:
patch:
summary: ユーザー情報の部分更新
description: ユーザー情報の特定フィールドを更新します
parameters:
- in: path
name: userId
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserPartial'
responses:
'200':
description: ユーザーが部分的に更新されました
components:
schemas:
UserPartial:
type: object
properties:
name:
type: string
example: Jane Doe
email:
type: string
format: email
example: [email protected]
6. 例（Examples）の追加
リクエストやレスポンスの例を記述します。
paths:
/users:
get:
responses:
'200':
description: ユーザーリストの取得成功
content:
application/json:
examples:
example-1:
summary: サンプルデータ
value:
- id: 1
name: John Doe
email: [email protected]
- id: 2
name: Jane Doe
email: [email protected]
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
format: email
example: [email protected]
Swagger YAML 記述コマンドと説明
以下は、Swagger (OpenAPI 3.0) における YAML 記述コマンドとその説明を洗い出したものです。 それぞれのコマンドは Swagger YAML ファイルの特定のセクションや目的に対応しています。
基本コマンド
openapi
- 概要: OpenAPI仕様のバージョンを指定します。
- 例:
openapi: 3.0.0
info
- 概要: APIの基本情報を記述します（タイトル、バージョン、説明など）。
- 例:
info: title: サンプルREST API version: 1.0.0 description: Swaggerドキュメントを用いたサンプルREST API
servers
- 概要: 利用可能なサーバーのリストを記述します。
- 例:
servers: - url: https://api.example.com/v1 description: 本番環境 - url: https://staging.example.com/v1 description: ステージング環境
Paths 定義
paths
- 概要: APIエンドポイントとその操作（HTTPメソッド）を定義します。
- 例:
paths: /users: get: summary: ユーザー一覧を取得 description: 全てのユーザー情報を取得します responses: '200': description: 正常なレスポンス content: application/json: schema: type: array items: $ref: '#/components/schemas/User'
parameters
- 概要: パスやクエリ文字列のパラメータを定義します。
- 例:
parameters: - in: path name: userId required: true schema: type: integer description: 取得するユーザーのID
requestBody
- 概要: リクエストの本文を記述します。
- 例:
requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/User'
responses
- 概要: APIのレスポンスを記述します（HTTPステータスコード別）。
- 例:
responses: '200': description: 正常なレスポンス content: application/json: schema: type: array items: $ref: '#/components/schemas/User'
Components 定義
components
- 概要: 再利用可能なスキーマやパラメータ、セキュリティ定義を記述します。
- 例:
components: schemas: User: type: object required: - id - name properties: id: type: integer example: 1 name: type: string example: John Doe email: type: string format: email example: [email protected]
認証設定
security
- 概要: APIの認証要件を記述します。
- 例:
security: - bearerAuth: []
securitySchemes
- 概要: 認証スキーム（例：JWT）を記述します。
- 例:
components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
データ例 (Examples)
examples
- 概要: リクエストやレスポンスの例を記述します。
- 例:
examples: example-1: summary: サンプルデータ value: - id: 1 name: John Doe email: [email protected] - id: 2 name: Jane Doe email: [email protected]