swaggerとは

古の時代、API仕様書はwordやexcelで表現され、各所に共有されるというのが一般的でした。
ですが近年、API仕様を表現する際にはswaggerを利用するのが最も効率的で、保守性が高く、世間一般で仕様化され、見やすいというのもあり、一般化されてきたのではないのでしょうか

今回はそんなswaggerの書き方について、まずは書くために覚えておきたいポイントを解説していこうかと思います！

どう書いてくか

swagger editorで書く

公式がWeb上に提供しているツールを利用し、すぐにでもswaggerの執筆が可能となっています！
なにをインストールする必要もなく開始1秒で利用できるので、私も重宝してます
なお、ページを開くとサンプルAPI仕様がすでにある状態でのスタートとなり、記法の参考などにもなります

vscodeで書く

必要なプラグインをインストールし、vscode上で執筆するパターンもありです（私は普段こちらの方法です）
おすすめはこちらのプラグインです！

win：Ctrl + Shift + P
mac：command + Shift + P
でvscodeのコマンドパレットを開いて、「Preview Swagger」を選択することですぐに内容を確認できるので便利です

書き方

まず最低限覚えるべきはpaths。pathsの中さえかければなんとかなる

いろんなことを覚えるのは後にして、まずはpaths内をしっかり書けるようになりましょう！
それさえできればAPI仕様を表現できるようになるのと同義になります！

では書いていきますが、以下の順で進めていきましょう

pathを書く
リクエストメソッド書く
API名を書く（省略可能）
リクエストパラメータ書く（省略可能）
リクエストレスポンス書く

  /tests: # ここがpath（URLの一部になります）
    get:  # ここがリクエストメソッド
      summary: テストAPI # API名
      parameters: # リクエストパラメータ
      - name: test
        in: query
        schema:
          type: string
      responses: # リクエストレスポンス
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

このAPIは以下のリクエストメソッド、URLで呼び出し可能であるという表現となります

GET http://{domain}/tests?test=xxx

content内のおまじないを覚える

responsesの中身を記述している時、中級者でも書き方忘れる場合が多くあります
ですが早いうちに簡単な傾向さえ覚えてしまえば、今後のswagger開発が捗ること間違いなしです！

content → Content-Type → schema

swaggerでAPI仕様書を書くタイプの仕事をしているひとの多くは、Content-Typeは「application/json」としてるのではないでしょうか
ですので、以下のように読み替えて覚えましょう
content → application/json → schema

  responses:
    200: # ステータスコード
      description: success operation
      # ここから
      content:
        application/json:
          schema:
      # ここまで
            type: object
            properties:
              data:
                type: string

content → application/json → schema

type:arrayはitems、type:objectはpropertiesで覚える

json構造を書いていると、 []これと{}これを使い分けなければいけませんね
どうしたらどうなる、を覚えていきましょう

[]：type:array
{}：type:object
と表現すると思った形になると思います

さらに、type:arrayの次にはitemsを、type:objectの次にはpropertiesを続ける必要があるのもルールです！

実際に見てみましょう

type: array

  responses:
    200:
      description: success operation
      content:
        application/json:
          schema:
            # ここから
            type: array
            items:
            # ここまで
              type: string 
# jsonは以下のようになる
# [
#   "string"
# ]

type: object

  responses:
    200:
      description: success operation
      content:
        application/json:
          schema:
            # ここから
            type: object
            properties:
            # ここまで
              data:
                type: string
# jsonは以下のようになる
# {
#   data: "string"
# }

[]：type:array
{}：type:object
type:arrayの次にはitems
type:objectの次にはproperties

値の受け渡し方、GETはparameters、POSTはrequestBodyに書く

GETとPOSTは一般的にデータの受け渡し方法に違いがあり、それはswaggerでも表現方法を分ける必要があります
GET：クエリーパラメータ
POST：リクエストボディ

クエリーパラメータ

  /tests:
    get:
      summary: テストAPI（一覧）
      parameters:
      - name: data
        in: query
        schema:
          type: string

リクエストボディ

  /tests:
    post:
      summary: テスト登録API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string

Tips：データ受け渡し方法の違いは、詳しくはこちらの記事がすごい参考になります

パスパラメータはGET/POSTに関わらずparametersに

一点注意点があります！
POSTであってもパスパラメータについてはparametersに記述する必要があります
また、その際にはparametersとrequestBodyは共存できます

  /tests/{id}/hoge:
    post:
      summary: テストほげ登録API
      # ここから
      parameters:
      - name: id
        in: path # in:pathになっているのにも注目
        required: true # パスパラメータは必須指定が求められます
      # ここまで
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string

パスパラメータはGET/POSTに関わらずparametersに書きましょう！
さらに、parametersとrequestBodyは共存できます

requestBodyとresponsesは基本的に構造は同じ

requestBodyが出てきてお気づきの方もいるかと思いますが、requestBodyとresponsesのステータスコード以下の構造は同じです！

  /tests/{id}/hoge:
    post:
      summary: テストほげ登録API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        ## ここから
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
        ## ここまでと
      responses:
        200:
          description: success operation
          ## ここから
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
          ## ここまで

最後にいろんなパターンのswaggerを書いてみたので共有します

openapi: 3.0.3
info:
  title: test-api
  version: 0.0.1
tags:
  - name: user
    description: ユーザー情報
paths:
  /users:
    get:
      tags:
        - user
      summary: ユーザー一覧API
      description: |
        ユーザーをデフォルトで全件取得して返却します <br>
        idの昇順。
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    address:
                      type: string
                    birthday:
                      type: string
                      format: date
                      example: "1999-01-01"
                      nullable: true
                    age:
                      type: integer
                      nullable: true
                    sex:
                      type: string
                      enum:
                        - MALE
                        - FEMALE
                    memberType:
                      type: string
                      nullable: true
                      enum:
                        - GENERAL
                        - SPECIAL
                        - CHILD
                        - SENIOR
    post:
      tags:
        - user
      summary: ユーザー登録API
      requestBody:
        content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  address:
                    type: string
                  birthday:
                    type: string
                    format: date
                    example: "1909-01-01"
                    nullable: true
                  age:
                    type: integer
                    nullable: true
                  sex:
                    type: string
                    enum:
                      - MALE
                      - FEMALE
                  memberType:
                    type: string
                    nullable: true
                    enum:
                      - GENERAL
                      - SPECIAL
                      - CHILD
                      - SENIOR
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  address:
                    type: string
                  birthday:
                    type: string
                    format: date
                    example: "1909-01-01"
                    nullable: true
                  age:
                    type: integer
                    nullable: true
                  sex:
                    type: string
                    enum:
                      - MALE
                      - FEMALE
                  memberType:
                    type: string
                    nullable: true
                    enum:
                      - GENERAL
                      - SPECIAL
                      - CHILD
                      - SENIOR

  /users/{userId}:
    get:
      tags:
        - user
      summary: ユーザー詳細API
      description: |
        ユーザー詳細を取得して返却します <br>
      parameters:
      - name: userId
        in: path
        description: ユーザーID
        required: true
        schema:
          type: string
          example: 248c8027-b752-db4c-76c1-fb22a05e9591
          nullable: false
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  address:
                    type: string
                  birthday:
                    type: string
                    format: date
                    example: "1909-01-01"
                    nullable: true
                  age:
                    type: integer
                    nullable: true
                  sex:
                    type: string
                    enum:
                      - MALE
                      - FEMALE
                  memberType:
                    type: string
                    nullable: true
                    enum:
                      - GENERAL
                      - SPECIAL
                      - CHILD
                      - SENIOR

  /tests/{id}:
    get:
      summary: テストAPI（詳細）
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: test
        in: query
        schema:
          type: string
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    
  /tests:
    get:
      summary: テストAPI（一覧）
      parameters:
      - name: test
        in: query
        schema:
          type: string
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

    post:
      summary: テスト登録API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string

  /tests/{id}/hoge:
    post:
      summary: テストほげ登録API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
      responses:
        200:
          description: success operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string