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

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

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

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

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

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

Swaggerって？

Swaggerは、OpenAPI仕様で作成されたオープンソースツール。REST APIの設計や構築、ドキュメント作成に役立ちます。

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

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

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

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

Swaggerの基本構文

エクセルと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形式)

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: 想定外エラー

パスに関して

書き方は、以下になります。(直感的に書けますね)

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する

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

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

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

パラメータに関して

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

  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

正常系・異常系に関して

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

      responses:
        200:

  …

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

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

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

400:

description:  エラーメッセージ

レスポンスに関して

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

タグの設定に関して

最後にタグについて解説して終わります。

タグを設定することで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設計書を作成していきましょう。