概要

RESTfulAPIを実装する機会ができ、その際にAPIの仕様をコードで管理したく、よく聞くSwaggerについて調べたのでそのまとめです。

Swagger について

SwaggerはSmarter Bear社が開発するRESTful APIを構築するためのオープンソースフレームワークです。
RESTful APIのインターフェースを表現するための標準フォーマットがSwaggerです。
Version Preffixがついている場合はこのフォーマットを指します。

Smarter Bear社は同時に、Swaggerの標準フォーマットに則ったドキュメントと、そのドキュメントを記述するエディタと、ドキュメントからHTMLや実装の雛形を生成するツールをSwagger Toolsとして開発しています。

Tool	description
Swagger Spec	Swaggerの標準フォーマットに則ったドキュメント(JSON/YAML)
Swagger Editor	Swagger Specを記述するためのエディタ
Swagger UI	Swagger SpecからHTMLを自動生成するツール
Swagger Codegen	Swagger Specから実装の雛形を自動生成するツール
Swagger Hub	Swagger UIのホスティングサービス

Open API Specification 3.0 について

Swaggerは2017年に、Smarter Bear社からOpen API Initiativeに寄贈されて、名称がOpen API Specificationに変更になりました。
これまで標準仕様を指す時はVersion Preffixを付けてSwagger2.0と表現されることが多かったですが、バージョン3.0からはOpen API Specification 3.0 (OAS3.0)と表現されます。

ややこしいですが、寄贈されたのはあくまで標準仕様だけで、Swagger Tool群はSmarter Bear社が引き続き開発を継続しているので、こちらの名称はOpen API Specification Specみたいなことにはならず、Swagger Specのままです。

Swagger Spec 記法について

root階層の項目

openapi

セマンティックなVersionを指定します。2.0まではswaggerでした。

security

認証がある場合はここに記述します。公式ドキュメント

info

API全体の情報について記載します。

servers

接続先情報です。

paths

APIのURL情報について記載します。パラメーターやレスポンスはcomponentに用意し、"#/components/parameters/***"や"#/components/schemas/***"等の形で指定。

components

parameters, schemas, responsesの３項目が基本。APIサーバーのリクエストパラメータはparameters、レスポンスJSON/XMLはschemas、サーバーエラー等の共通レスポンスはresponsesに定義します。
componentにパラメータやレスポンスなどの情報をモデル化してまとめて記載することで、再利用可能で、Swagger Spec全体の見通しもよくなります。

まとめ

公式ドキュメントのパラメータの基本情報とExampleの指定については、SwaggerSpecを記載していく上でかなり助けになりました。
リポジトリでファイル管理できて、コマンド一つで仕様書として吐き出せるのでSwagger、便利です。