SwaggerでAPI仕様書を作成

# はじめに

API仕様書をSwagger（OpenAPI）で作成する際の手順とポイントをまとめた備忘録です。

## なぜOpenAPIを使うのか？

* **自動生成**: OpenAPIの定義からドキュメントやクライアントコードを自動生成できます。
* **可読性**: YAML／JSON形式で仕様が明文化され、チーム内で共有しやすくなります。
* **検証ツール**: Swagger UIやVSCodeプラグインでリアルタイムにプレビュー＆バリデーションが可能です。

# 開発環境

| ツール            | バージョン／用途                |
| -------------- | ----------------------- |
| macOS          | macOS Catalina以降を想定     |
| VSCode         | エディタ                    |
| Swagger Viewer | VSCode拡張機能（API定義をプレビュー） |

# 作成手順

## 1. YAMLファイルを作成

1. プロジェクト直下に `blog-api.yaml` を用意
2. OpenAPI 3.0.2 を指定

```yaml
openapi: "3.0.2"
```

## 2. Infoセクション

* `info` にはAPI全体のメタ情報を記載

  * `title`: ドキュメント名
  * `description`: 説明文
  * `version`: バージョン管理用

```yaml
info:
  title: "API連携"
  description: "ブログ記事取得APIの仕様書"
  version: "1.0"
```


## 3. サーバー定義

* `servers` には動作環境を列挙

  * URL: 実行先エンドポイント
  * 説明: 環境名など

```yaml
servers:
  - url: "https://localhost"
    description: "ローカル環境"
```

## 4. タグ（tags）

* エンドポイントを機能別に分類
* UI上でのグルーピングに利用される

```yaml
tags:
  - name: "ブログ記事"
    description: "ブログ記事に関する操作"
```

## 5. pathsセクション

* 各APIパスとメソッドを定義
* 詳細:

  * `security`: 認証方式（Bearerトークンなど）
  * `summary`: 機能の要約
  * `description`: 詳細説明（改行は `|` でブロック指定）
  * `parameters`: 入力パラメータの場所、名前、型、説明など
  * `responses`: レスポンスの型やステータスコード

```yaml
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セクション

### セキュリティスキーム

```yaml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "AuthorizationヘッダーにBearerトークンを含めてください。"
```

### スキーマ定義

* 各レスポンスボディの構造を `schemas` で定義
* 再利用可能で、他のエンドポイントでも参照可能

```yaml
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` でプレビューを常に表示

# 見た目
- こんなイメージになります

![スクリーンショット 2025-05-11 12.33.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/923146/6873e5d4-914f-4ff3-adea-abf687168a83.png)
![スクリーンショット 2025-05-11 12.33.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/923146/15d2fcf1-4c24-4cf7-9e24-467f3994109e.png)
![スクリーンショット 2025-05-11 12.33.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/923146/710439ca-0708-4c9f-a2d4-e9f09cf906b2.png)

# まとめ
Swagger使用した時の備忘録としてまとめ

# 参考記事

* [API仕様を簡単に作成&管理しよう！](https://tech.arms-soft.co.jp/entry/2023/01/18/090000)
* [VSCodeで効率的にswaggerを書く。](https://qiita.com/kawasukeeee/items/e0973f762e12aaa256e2)
* [Swagger Viewer (VSCode Marketplace)](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)
* [OpenAPI Specification (公式ドキュメント)](https://swagger.io/specification/)