はじめに
API仕様書をSwagger（OpenAPI）で作成する際の手順とポイントをまとめた備忘録です。
なぜOpenAPIを使うのか？
- 自動生成: OpenAPIの定義からドキュメントやクライアントコードを自動生成できます。
- 可読性: YAML／JSON形式で仕様が明文化され、チーム内で共有しやすくなります。
- 検証ツール: Swagger UIやVSCodeプラグインでリアルタイムにプレビュー＆バリデーションが可能です。
開発環境
| ツール | バージョン／用途 |
|---|---|
| macOS | macOS Catalina以降を想定 |
| VSCode | エディタ |
| Swagger Viewer | VSCode拡張機能（API定義をプレビュー） |
作成手順
1. YAMLファイルを作成
- プロジェクト直下に
blog-api.yamlを用意 - OpenAPI 3.0.2 を指定
openapi: "3.0.2"
2. Infoセクション
-
infoにはAPI全体のメタ情報を記載-
title: ドキュメント名 -
description: 説明文 -
version: バージョン管理用
-
info:
title: "API連携"
description: "ブログ記事取得APIの仕様書"
version: "1.0"
3. サーバー定義
-
serversには動作環境を列挙- URL: 実行先エンドポイント
- 説明: 環境名など
servers:
- url: "https://localhost"
description: "ローカル環境"
4. タグ（tags）
- エンドポイントを機能別に分類
- UI上でのグルーピングに利用される
tags:
- name: "ブログ記事"
description: "ブログ記事に関する操作"
5. pathsセクション
-
各APIパスとメソッドを定義
-
詳細:
-
security: 認証方式（Bearerトークンなど） -
summary: 機能の要約 -
description: 詳細説明（改行は|でブロック指定） -
parameters: 入力パラメータの場所、名前、型、説明など -
responses: レスポンスの型やステータスコード
-
paths:
/api/blog:
get:
security:
- BearerAuth: []
summary: "ブログ記事一覧を取得"
description: |
ブログ記事の一覧を取得します。
- title: タイトルで絞り込み
- status: 公開ステータスで絞り込み
parameters:
- in: "query"
name: "title"
schema:
type: "string"
description: "タイトルでフィルタリング"
# 他のパラメータも同様に記載
パラメータ詳細
| in | name | type | 説明 |
|---|---|---|---|
| header | Accept | string |
application/json を指定 |
| query | title | string | タイトルでフィルタリング |
| query | status | integer | 0: 公開, 1: 非公開, 2: 下書き |
| query | category | string | カテゴリでフィルタリング |
| query | page | integer | ページ番号 |
6. componentsセクション
セキュリティスキーム
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: "AuthorizationヘッダーにBearerトークンを含めてください。"
スキーマ定義
- 各レスポンスボディの構造を
schemasで定義 - 再利用可能で、他のエンドポイントでも参照可能
components:
schemas:
BlogPost:
type: object
properties:
id:
type: integer
format: int64
description: ブログ記事ID
title:
type: string
description: ブログタイトル
status:
type: integer
enum: [0, 1, 2]
description: ステータス (0=公開,1=非公開,2=下書き)
required:
- id
- title
- status
Tips & 注意点
-
コロンや括弧を含む値 は必ずダブルクォートで囲む
-
日付文字列 は
format: date-timeを指定し、ISO 8601形式に合わせる -
長い説明文 は
|を使ったブロック文字列で可読性向上 -
VSCodeの設定
-
.yamlファイルの言語モードをOpenAPI／YAMLにする -
Swagger Viewerでプレビューを常に表示
-
見た目
- こんなイメージになります
まとめ
Swagger使用した時の備忘録としてまとめ