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編〜 を公開しました。