Go to Qiita Advent Calendar 2024 Top
LoginSignup
6
9

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@oden141

【Swagger】Swagger Spec (yaml) の書き方 〜PUT, POST, DELETE編〜

Last updated at Posted at 2020-04-19

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: "ぜんしんの　さいぼうを　くみかえて　みたもの　そっくりに　へんしんする"

20200419-224836.png

解説

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: "ぜんしんの　さいぼうを　くみかえて　みたもの　そっくりに　へんしんする"

20200419-231826.png

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"

20200419-232403.png

まとめ

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

おまけ

6
9
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
6
9

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?