【脱エクセル】Swaggerを使ってAPI設計書を書く

「エクセルでAPI設計書を書くのは卒業したい…」

「Swaggerを使ってAPI設計書を作成したいな….」

この記事では上記の悩みを解決します。

Swaggerは、いい感じのUIでAPI設計書をかけるものです。

今回は、そんなSwaggerを用いてAPI設計書を作成する方法をみなさんにお伝えしていきます。

エクセルでAPI設計書を書くのはもうやめだ！！って人はぜひこの記事を参考にしてみてくださいね。

# Swaggerって？

Swaggerは、[OpenAPI仕様](https://swagger.io/docs/specification/about/)で作成されたオープンソースツール。REST APIの設計や構築、ドキュメント作成に役立ちます。

利用可能なエンドポイントやパラメータ、レスポンス、エラーハンドリングなど記載することができます。

実際に見た方が早いかと思うので、swaggerで作成したAPIの設計書になります↓

![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FY6PdMFtK7PzfDIKd?alt=media&token=b1ab003c-5582-4292-801e-e277c8d0ee1c)

![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FagjoBxm0EKdbbOWa?alt=media&token=57e64d75-7410-4018-80ee-bfee4f571cc2)

![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FvsV6SUglxAYOikd0?alt=media&token=25952132-52c6-4211-a1a5-050c83720453)

![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FkwEVpMohwzHg8vJl?alt=media&token=80ec377d-36c5-4f48-bd13-a32d7b80f391)

Swaggerは、YAML、JSON形式で記述することができ、パス、パラメータなど記載することでAPI設計書を作成していきます。

基本的な書き方は以下です。

[Swaggerの基本構文](https://swagger.io/docs/specification/basic-structure/)

# エクセルとSwaggerの比較

API設計書を書くにあたり、エクセルとSwaggerの比較をしていきたいと思います。

## エクセルの場合：

- シンプルで使いやすい
- API設計書はエクセルで作成するのが一般的
- API設計書のフォーマットなどを考えるのが面倒
- 体裁など(改行や処理の番号降るなど)の作業が発生する
- かなり細かいところまで自由に記載できる(エクセルの機能が豊富だから)
- 古びた老人のような感じがする

## Swaggerの場合：

- モダンな感じがする
- swagger用のファイルのコードをいじる必要はあるが、ドキュメントを自動で生成してくれる
- 決まったレイアウトでデザインやフォーマットをいちいち考えなくていい
- 保守性や管理が楽
- swaggerの構文などに縛られる
- 構文理解など、慣れるまで時間かかる

エクセルとswaggerを比較した際に、swaggerの利点は「swaggerがいい感じにドキュメントのフォーマットを自動で生成してくれる」「保守性がエクセルに比べて楽」だと感じます。

# Swaggerの書き方をざっくり解説

それでは実際にSwaggerを触っていきます。

まずは、vscodeを利用している場合は、以下の拡張機能を入れた方がいいです。

## SwaggerのUI拡張機能

VScodeの拡張機能よりSwagger Viewerをインストールする

インストールができたら、以下の操作でswaggerのUIを開けます。

①コマンドパレットを開く

macの場合：shift+command+P

windowsの場合： Shift+Alt+P

②コマンドパレットからPreview Swaggerを選択する

## Swaggerの書き方に関して

ユーザー情報のAPI設計の書き方を通してswaggerの書き方を見ていきます。

要点はこんな感じです。

- パスの書き方
- パラメータの書き方
- 正常、異常系の書き方
- レスポンスの書き方
- タグの設定

今回解説するコードは以下になります。(YAML形式)

```yaml
openapi: '3.0.2'
info:
  title: skillcode API設計書
  version: '1.0'
servers:
  - url: http://localhost:8000
    description: ローカル環境

tags:
  - name: "users"
    description: "ユーザー関連"

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]
      parameters:
        - name: user_id
          in: path
          required: true
          description: ユーザーID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 1
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザーID
                    format: int64
                    minimum: 1
                    example: 1
                  user_name:
                    type: string
                    description: ユーザー名
                    maxLength: 50
                    example: 山田太郎
                  email:
                    type: string
                    description: メールアドレス
                    maxLength: 255
                    example: yamada@google.com
                  self_introduction:
                    type: string
                    description: 自己紹介
                    nullable: true
                    format: longText
                    example: 自己紹介文
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー
```

### パスに関して
![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FvCyDBRPlMUS7js7a?alt=media&token=992837a8-ea97-4571-97c9-6e9035bfa721)

書き方は、以下になります。(直感的に書けますね)
```
paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
```

pathsにエンドポイントとHTTPメソッドを指定できます。

summaryはAPI名、descriptionにはAPIの説明とか書けばOKです。

tagsに関しては、後ほど解説します。

### パラメータに関して
![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FaZqxk1kOSzBQlaJY?alt=media&token=9de61686-a9a0-423d-9c01-febe8f353273)

書き方は、以下になります。

      parameters:
        - name: user_id
          in: path
          required: true
          description: ユーザーID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 1

parametersには、パラメータを記載していきます。

パラメータ名を書く場合は、-name: パラメータ名…のように記述すればOKです。

-inはパラメータの場所を表しています。query, header, path, formDataなどがあります。

requiredは必須か、NULL許可かを表しています。

schemaには、型やサンプル値などを記載することが可能です。

詳細は、以下を確認してください。

[Swaggerのschema](https://swagger.io/docs/specification/describing-parameters/)

### 正常系・異常系に関して
![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2Fu297iRSvZwJnenFD?alt=media&token=7af09e85-0c65-4138-8da7-9d02db6c209b)

書き方は以下になります。
```
      responses:
        200:

  …

        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー
```

正常系や異常系は上記のように、responsesの部分に記載していく形になります。

独自にエラーレスポンスを返す場合でも、以下のように書いていけばOKです。
```
400:

description:  エラーメッセージ
```

### レスポンスに関して
![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2Fu297iRSvZwJnenFD?alt=media&token=7af09e85-0c65-4138-8da7-9d02db6c209b)

JSON形式でレスポンスを返す場合は以下のようなサンプルコードを書けばOKです。

          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザーID
                    format: int64
                    minimum: 1
                    example: 1

schemaで使われるデータ型に関しては、

- string
- number
- integer
- boolean
- array
- object

などがあります。

また、formatに関しては、

- int32(符号付き32ビット)
- int64(符号付き64ビット)
- float(浮動小数)
- double(倍精度浮動小数)
- password
- date
- date-time
- uuid

などがあります。

[swaggerのtype](https://swagger.io/docs/specification/describing-responses/)

### タグの設定に関して

最後にタグについて解説して終わります。
![image](https://firebasestorage.googleapis.com/v0/b/ciita-c6ea6.appspot.com/o/user%2Fimages%2FmySkXB2UiJDV04qb?alt=media&token=291a997a-82bb-442d-bab7-0139157db760)

タグを設定することでAPIをまとめられます。

usersというタグでAPIをまとめてみましょう。

今回は、もともとあるGETリクエストのAPIにPOSTを足しました。

追加した内容は、/usersから始まるコードからになります。

```
tags:
  - name: "users"
    description: "ユーザー関連"

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]
      parameters:
        - name: user_id
          in: path
          required: true
          description: ユーザーID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 1
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザーID
                    format: int64
                    minimum: 1
                    example: 1
                  user_name:
                    type: string
                    description: ユーザー名
                    maxLength: 50
                    example: 山田太郎
                  email:
                    type: string
                    description: メールアドレス
                    maxLength: 255
                    example: yamada@google.com
                  self_introduction:
                    type: string
                    description: 自己紹介
                    nullable: true
                    format: longText
                    example: 自己紹介文
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー
  /users:
    post:
      summary: ユーザー情報登録API
      description: ユーザー情報を登録するAPI
      tags: ["users"]
      parameters:
        - name: user_name
          in: query
          required: true
          description: ユーザー名
          schema:
            type: string
            example: 山田
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー
```

タグの設定のやり方に関しては、以下のようにまずはタグ名を定義します。

```
tags:
  - name: "users"
    description: "ユーザー関連"
```

タグ名を定義したら、HTTPリクエストの部分で呼び出すタグと紐付けるだけです。
```
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]

…….

  /users:
    post:
      summary: ユーザー情報登録API
      description: ユーザー情報を登録するAPI
      tags: ["users"]
```

このように記載することで、今回の場合だとusersというタグにAPIがまとめられます。
## まとめ
今回はswaggerを使って脱エクセルでAPI設計書を作成する方法を説明しました。swaggerを勉強して、モダンなAPI設計書を作成していきましょう。