SwaggerでAPI設計書を管理する際のyamlの記法をまとめる。
今回は put post delete 編です。

Put

< Sample >

    put:
      tags:
        - "ポケモン情報更新API"
      summary: "ポケモン情報更新API"
      parameters:
        - name: "id"
          in: "path"
          description: "ポケモンを特定する一意のID"
          required: true
          type: "string"
        - name: "name"
          in: "path"
          description: "ポケモンの名前"
          required: true
          type: "string"
      requestBody:
        description: "登録したいポケモンのIDと名前を送信する。"
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                pokemon-base-info:
                  $ref: "#/definitions/pokemon-base-info"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  scccess:
                    type: "string"
                    example: UPDATED
        400:
          description: "BadRequest"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: BAD_REQUEST
                  message:
                    type: string
                    example: BAD_REQUEST
        403:
          description: "Forbidden"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: FORBIDDEN
                  message:
                    type: string
                    example: FORBIDDEN
        404:
          description: "NotFound"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: NOT_FOUND
                  message:
                    type: string
                    example: NOT_FOUND

definitions:
  pokemon-base-info:
    type: "array"
    items:
      type: "object"
      properties:
        id:
          type: "string"
        name:
          type: "string"
        type:
          type: "string"
        comment:
          type: "string"
    example:
      - id: "007"
        name: "ゼニガメ"
        type: "みず"
        comment: "こうらに　とじこもり　みをまもる。"
      - id: "132"
        name: "メタモン"
        type: "ノーマル"
        comment: "ぜんしんの　さいぼうを　くみかえて　みたもの　そっくりに　へんしんする"

解説

GET編と同じ部分も多いので、異なる部分のみの解説でっっっす

`requestBody`

      requestBody:
        description: "登録したいポケモンのIDと名前を送信する。"
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                pokemon-base-info:
                  $ref: "#/definitions/pokemon-base-info"

フィールド名	説明
requestBody	登録、更新する際の内容を指定
description	リクエストボディの説明
required	パラメーターの必須、非必須（必須=true）
content	MINEタイプ
schema	スキーマオブジェクト
type	スキーマオブジェクトのタイプ（object, array）

タイプによってこの後の記述が変わる。（わからなかったらこちらを参照してください）

知ってると便利！！

putだけでなく、他のドキュメント作成でも使いそうなパーツは、
definitions でパーツ化し、それを呼び出して使うことができる！

パーツ側

definitions:
  pokemon-base-info:
    type: "array"
    items:
      type: "object"
      properties:
        id:
          type: "string"
        name:
          type: "string"
        type:
          type: "string"
        comment:
          type: "string"
    example:
      - id: "007"
        name: "ゼニガメ"
        type: "みず"
        comment: "こうらに　とじこもり　みをまもる。"
      - id: "132"
        name: "メタモン"
        type: "ノーマル"
        comment: "ぜんしんの　さいぼうを　くみかえて　みたもの　そっくりに　へんしんする"

呼び出し側

              properties:
                pokemon-base-info:
                  $ref: "#/definitions/pokemon-base-info"

pokemon-base-info: は "#/definitions/pokemon-base-info"から参照してね、という意味。

Post

特に新しい解説はないので、サンプルのみ投下。
パーツはputで用意した definitions を使います。

    post:
      tags:
        - "ポケモン登録API"
      summary: "ポケモン登録API"
      parameters:
        - name: "id"
          in: "path"
          description: "ポケモンを特定する一意のID"
          required: true
          type: "string"
        - name: "name"
          in: "path"
          description: "ポケモンの名前"
          required: true
          type: "string"
      requestBody:
        description: "登録したいポケモンのIDと名前を送信する。"
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                pokemon-base-info:
                  $ref: "#/definitions/pokemon-base-info"
      responses:
        201:
          description: "Success"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  success:
                    type: "string"
                    example: "REGISTERED"
        400:
          description: "BadRequest"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: BAD_REQUEST
                  message:
                    type: string
                    example: "BAD_REQUEST"
        409:
          description: "Conflict"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: "CONFLICT"
                  message:
                    type: string
                    example: "CONFLICT"

definitions:
  pokemon-base-info:
    type: "array"
    items:
      type: "object"
      properties:
        id:
          type: "string"
        name:
          type: "string"
        type:
          type: "string"
        comment:
          type: "string"
    example:
      - id: "007"
        name: "ゼニガメ"
        type: "みず"
        comment: "こうらに　とじこもり　みをまもる。"
      - id: "132"
        name: "メタモン"
        type: "ノーマル"
        comment: "ぜんしんの　さいぼうを　くみかえて　みたもの　そっくりに　へんしんする"

Delete

特に新しい解説はないので、サンプルのみ投下。

    delete:
      tags:
        - "ポケモン削除API"
      summary: "ポケモン削除API"
      parameters:
        - name: "id"
          in: "path"
          description: "ポケモンを特定する一意のID"
          required: true
          type: "string"
        - name: "name"
          in: "path"
          description: "ポケモンの名前"
          required: true
          type: "string"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  success:
                    type: "string"
                    example: "DELETED"
        400:
          description: "BadRequest"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: "BAD_REQUEST"
                  message:
                    type: string
                    example: "BAD_REQUEST"
        403:
          description: "Forbidden"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: "FORBIDDEN"
                  message:
                    type: string
                    example: "FORBIDDEN"
        404:
          description: "NotFound"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: string
                    example: "NOT_FOUND"
                  message:
                    type: string
                    example: "NOT_FOUND"

まとめ

yaml記法編完結〜〜！そして、ポケモンAPIドキュメントも完成しました。
ずいぶん考えながら記事を書いたので、しばらくは覚えていられると思った。
あと、今すごく眠い。

おまけ

API設計書をSwaggerで管理する　公開しました。
Swagger Spec (yaml) の書き方〜GET編〜　を公開しました。