Swagger
What’s??
皆さんはSwaggerをご存知でしょうか？
Swaggerとは、RESTful APIのAPIドキュメントを生成するためのオープンソースのフレームワークのことです。
「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進しており、その団体が考え出した規格のひとつがSwaggerです。
エクセルなどとは違い、テキストベースのファイルなのでGit管理がしやすいのもメリットの一つです。
Swaggerには、幾つかのモジュールがあります。
Swagger Spec
Swagger SpecはSwaggerの書式で記述した仕様書の事で、JSONもしくはYAML形式で記述します。
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
<pSwagger Editer>はSwaggerSpecファイルの生成や編集を行うためのツールです。
ブラウザ上で動作可能で、左側にYAMLまたはJSONで記述します。
そして、右側には左の記述をもとに生成されたドキュメントがリアルタイムに更新されるので、構文チェックを行いながら定義を行うことが出来ます。
Swagger UI
Swagger UIはSwaggerSpecを元に、HTML形式のドキュメントを生成するためのツールです。SwaggerEditorから各言語で自動生成することが可能です。
SwaggerCodegen
Swagger Codegenとは、SwaggerSpecから， クライアントライブラリやスタブサーバー、ドキュメントを生成するツールです。
CLIから生成をすることが出来ますが、先ほど紹介したSwagger Editorからも生成することが可能です。
終わりに
以上のように、SwaggerはAPIドキュメントに関して定義から閲覧までを完全にサポートしており、API開発においてとても便利です。
まだ、エクセルやパワポなどで管理している場合は、効率が格段に変わりますので是非導入してみてはいかがでしょうか？