投稿日：
【炎上回避】APIドキュメントはSwaggerで定義すると幸せになれる説
YouTubeも見てね♪
ねこじゃすり
猫を魅了する魔法の装備品！
Anker PowerCor
旅行には必須の大容量モバイルバッテリー！
【最新機種】GoPro hero11 Black
最新機種でVlogの思い出を撮影しよう！
[ノースフェイス] THE NORTH FACE メンズ アウター マウンテンライトジャケット
防水暴風で耐久性抜群なので旅行で大活躍です！
モンスターエナジー 355ml×24本 [エナジードリンク]
脳を活性化させるにはこれ！
BANDAI SPIRITS ULTIMAGEAR 遊戯王 千年パズル 1/1スケール
もう一人の僕を呼び覚ませ！！
MOFT X 【新型 ミニマム版】 iPhone対応 スマホスタンド
Amazon一番人気のスマホスタンド！カード類も収納出来てかさ張らないのでオススメです！
目次
Swagger
What’s??
皆さんはSwaggerをご存知でしょうか？
Swaggerとは、RESTful APIのAPIドキュメントを生成するためのオープンソースのフレームワークのことです。
「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進しており、その団体が考え出した規格のひとつがSwaggerです。
エクセルなどとは違い、テキストベースのファイルなのでGit管理がしやすいのもメリットの一つです。
Swaggerには、幾つかのモジュールがあります。
Swagger Spec
Swagger SpecはSwaggerの書式で記述した仕様書の事で、JSONもしくはYAML形式で記述します。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
swagger: '2.0'
info:
version: "1.0.0"
title: "Sample Title"
host: "localhost"
schemes:
- https
basePath: "/"
produces:
- "application/json"
paths:
"/users":
get:
summary: Listing User
description: |
Listing User API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
responses:
200:
description: Successful responses
schema:
title: User List
type: object
properties:
users:
title: User List
type: array
items:
title: Users
type: object
properties:
id:
type: integer
description: User Id
example: 1001
name:
type: string
description: User Name
example: Yamada Taro
isPaidUser:
description: Paid User
type: boolean
example: false
post:
summary: Create User
description: |
Create New User API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
- name: request
in: body
required: true
schema:
title: User
type: object
properties:
name:
type: string
description: User Name
example: Yamada Taro
isPaidUser:
description: Paid User
type: boolean
example: false
responses:
201:
description: Create responses
schema:
title: Users
type: object
properties:
id:
type: integer
description: User Id
example: 1001
409:
description: Conflict responses
"/users/{id}":
get:
summary: Find User
description: |
Find User By Id API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
responses:
200:
description: Successful responses
schema:
title: Users
type: object
properties:
id:
type: integer
description: User Id
example: 1001
name:
type: string
description: User Name
example: Yamada Taro
isPaidUser:
description: Paid User
type: boolean
example: false
404:
description: Not Found responses
put:
summary: Modify User Content
description: |
Modify User Content API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
- name: request
in: body
required: true
schema:
title: User
type: object
properties:
name:
type: string
description: User Name
example: Yamada Taro
isPaidUser:
description: Paid User
type: boolean
example: false
responses:
200:
description: Update responses
404:
description: Not Found responses
patch:
summary: Modify User Attribute
description: |
Modify User Attribute API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
- name: request
in: body
required: true
schema:
title: User
type: object
properties:
name:
type: string
description: User Name
example: Yamada Taro
isPaidUser:
description: Paid User
type: boolean
example: false
responses:
200:
description: Update responses
404:
description: Not Found responses
delete:
summary: Delete User
description: |
Delete User API
parameters:
- name: id
in: path
description: User Id
required: true
type: integer
responses:
204:
description: Update responses
403:
description: Forbidden responses
404:
description: Not Found responses
|
Swagger Editer
Swagger Editer>はSwaggerSpecファイルの生成や編集を行うためのツールです。
ブラウザ上で動作可能で、左側にYAMLまたはJSONで記述します。
そして、右側には左の記述をもとに生成されたドキュメントがリアルタイムに更新されるので、構文チェックを行いながら定義を行うことが出来ます。
Swagger UI
Swagger UIはSwaggerSpecを元に、HTML形式のドキュメントを生成するためのツールです。
SwaggerEditorから各言語で自動生成することが可能です。
SwaggerCodegen
Swagger Codegenとは、SwaggerSpecから， クライアントライブラリやスタブサーバー、ドキュメントを生成するツールです。
CLIから生成をすることが出来ますが、先ほど紹介したSwagger Editorからも生成することが可能です。
SwaggerEditorから各言語で自動生成することが可能です。
CLIから生成をすることが出来ますが、先ほど紹介したSwagger Editorからも生成することが可能です。
終わりに
以上のように、SwaggerはAPIドキュメントに関して定義から閲覧までを完全にサポートしており、API開発においてとても便利です。
まだ、エクセルやパワポなどで管理している場合は、効率が格段に変わりますので是非導入してみてはいかがでしょうか？