tl;dr
- swaggerを使うとWebAPIの仕様書を決められたフォーマットに沿って作成できる
- API更新に追従して仕様書の自動更新ができる
- 将来的にはWebAPI仕様書の標準フォーマットになるかも？
メモ
- swagger coreとcodegenの役割が少し曖昧になっているから、明確化したい。
swaggerとは
- swaggerはREST APIのドキュメント記載に関するフォーマット仕様
- RESTful API標準化団体(Open API Initiative）が採用。OpenAPI Specificationとして定義されている。
- 実態はJSON(YAML)形式のAPI仕様書とそれを取り巻くツール群
- swaggerプロジェクト自体はフォーマット仕様以外にもドキュメントを書きやすくするツール、ドキュメント自動生成、ウェブベースのドキュメントビューワ等を提供している。
swaggerでのAPI仕様書生成方式
- トップダウン
- 仕様を定義（swagger editor）で定義ファイルを生成し、公開（swagger ui）
- 定義ファイルからソースコードを生成(swagger codegen)
- ボトムアップ
- 既に存在するREST APIのソースコードから定義を作成する（swagger core）
- コード内にはSwagger用のAnnotationが書いてあること前提（JavaDocのようなものか）
- 生成された定義を公開（swagger ui）
swaggerの構成要素
- Swagger Specification
- フォーマット仕様
- 仕様に沿ってJSON(YAML)形式でAPI定義を記述する。以下サンプル
swagger: '2.0'
info:
version: "1.0.0"
title: 日本語のテスト
paths:
/auth:
get:
description: |
test description
日本語説明文
parameters:
-
name: size
in: query
description: Size of array
required: true
type: number
format: double
responses:
200:
description: Successful responses
schema:
title: ArrayOfPersons
type: array
items:
title: Person
type: object
-
Swagger Specificationに沿って記述されたJSON(YAML)ファイルを編集するWebベースのツール。swaggerの公式ページで動作しているものを使うか、ツールをダウンロードしてローカルで動作させる。
-
ツールはNode.js製なのでローカルで使う場合は要Node.js
-
Swagger Specificationに沿って記述されたJSON(YAML)ファイルのビュワー。Webベースのインタフェース。公式ページでデモが公開されている。
-
swaggerの定義ファイル(json)から実際のプログラムコード（サーバ側・クライアント側）を生成するツール。
-
出力言語は様々（ruby, python, node, php）対応している。
-
実際のプログラムコードからswagger定義（json）を生成する。