Swagger

Swaggerとは

RESTfulAPIにおけるインターフェイスのフォーマット

Swagger Spec

全体像

Swagger書式によるAPI仕様書
yaml、jsonで保存

※swagger.yaml
swagger: “2.0”
info:
　title: “API(例)”
　description: “公開API一覧”
　version: “1.0.0”

paths:
#ユーザー画面
　/api/method1:
　　get:
　　　tags:
　　　　 - Method1 API
　　　description: “Method1の機能説明”
　　　
　　　parameters:
　　　　- name: “lease_type_ids”
　　　　　description: “パラメータの説明”
　　　　　required: true
　　　　　type: “string”
　　　　　
　　　responses:
　　　　”200″:
　　　　　description: “Method1正常時の挙動説明”
　　　　　schema:
　　　　　　title: ArrayOfPosts
　　　　　　type: array
　　　　　　items:
　　　　　　　title: Posts
　　　　　　　type: object
　　　　　　　properties:
　　　　　　　　name:
　　　　　　　　　type: string
　　　　　　　　title:
　　　　　　　　　type: string
　　　　”404″:
　　　　　　description: “検索結果が0件”
　　　　　　schema:
　　　　　　　type: “object”
　　　　　　　properties:
　　　　　　　　code:
　　　　　　　　　type: “string”
　　　　　　　　　example: “E999”
　/api/method2:
　　〜

リクエスト/レスポンス部

フィールド	機能	備考
summary	概要	120文字以内
description	説明
tags	swaggerオブジェクトとの関連付け名	配列で指定
parameters	リクエスト内容
responses	レスポンス内容
consumes/produces	MIME Type	配列で指定
schemes	APIの通信プロトコル	http/https/ws/wss 配列で指定
deprecated	Deprecatedか否か	true/false

パラメータ

一覧

パラメータ	機能	備考
name	パラメータ名	必須
in	パラメータ位置	必須
description	パラメータ説明
required	必須か否か	true/false
schema	bodyパラメータ	in=body時
type	パラメータデータ型(簡易)	in!=body時
format	パラメータデータ型(詳細)	in!=body時

in

in	機能
query
header
path
formData
body

type/format

type	format	機能
integer	int32/int64
number	float/double
string	formatなし/byte/binary/date/date-time/password
boolean
object
array
file

レスポンス

一覧

フィールド	機能	備考
description	説明
schema	レスポンス内容
headers	レスポンスヘッダー
example	レスポンス例

Swagger Editor

SwaggerSpecファイルをブラウザ上で編集するツール

Swagger UI

SwaggerSpecファイルをブラウザ上で表示するツール

http://{ホスト名}/swagger/index.html

Swagger Codegen

Swagger Specで記載された設計からクライアント/サーバコードを生成するコマンドラインツール
多くの言語、フレームワークに対応