Swagger定義ファイルを分割する
Swagger用ファイルを分割して記述しよう
Swaggerとは
Swaggerとは言語に依存しないREST APIのインターフェース仕様とそれに関連するツール/ライブラリのことです。
RESTful APIの記述標準化を目指している、MS/Google/IBMなどが参加しているグループ、
Open API Initiativeでは、APIの記述のためにSwaggerが採用されています。
Swaggerは以下のようなツールから構成されています。
- Swagger UI - swagger specをパースしてAPIドキュメント化するツール
- Swagger Codegen - swaggerの定義ファイルからプログラムコードを生成するツール
- Swagger Editor - オンラインで使用できるSwaggerエディタ
普通にswaggerの記述をする
まずは下記のように、普通にswagger.jsonを記述しましょう。
Swagger Editorで↓のコードを貼り付けてみると、
画面右部にAPIドキュメントが表示されます。
{
"swagger": "2.0",
"info": {
"title": "Uber API",
"description": "Move your app forward with the Uber API",
"version": "1.0.0"
},
"host": "api.uber.com",
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
"paths": {
"/me": {
"get": {
"summary": "User Profile",
"description": "The User Profile endpoint returns information.",
"responses": {
"200": {
"description": "Profile information for a user",
"schema": {
"$ref": "#/definitions/Profile"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
}
},
"definitions": {
"Profile": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First name of the Uber user."
},
"last_name": {
"type": "string",
"description": "Last name of the Uber user."
},
"email": {
"type": "string",
"description": "Email address of the Uber user"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
swaggerの問題点
swaggerである程度のサイズのAPIドキュメントを記述したことがあればわかると思いますが、
swagger.json/yamlファイルは肥大しがちです。
そんなときには、今回紹介するように、swagger.jsonファイルを分割して記述することが可能です。
環境
今回使用した動作環境は以下のとおりです。
- OS : MacOS X 10.10.5
- node : v5.8.0
分割して記述する
では、さきほどのswagger.jsonを分割して記述してみましょう。
まずはルート直下に、index.jsonを下記のように記述します。
{
"swagger": "2.0",
"info": {
"title": "Uber API",
"description": "Move your app forward with the Uber API",
"version": "1.0.0"
},
"host": "api.uber.com",
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
"paths": {
"$ref": "./paths/index.json"
},
"definitions": {
"$ref": "./definitions/index.json"
}
}
$refを使用して、この後記述するファイルパスを指定しています。
ここではpathsとdefinitionsのindexファイルを指定します。
paths/index.jsonは下記のとおりです。
{
"/me": {
"$ref": "./me.json"
}
}
ここからさらにme.jsonを指定しています。
{
"get": {
"summary": "User Profile",
"description": "The User Profile endpoint returns information.",
"responses": {
"200": {
"description": "Profile information for a user",
"schema": {
"$ref": "#/definitions/Profile"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
}
}
definitions/index.jsonも別ファイルとして指定しているので、作成しましょう。
{
"Profile": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First name of the Uber user."
},
"last_name": {
"type": "string",
"description": "Last name of the Uber user."
},
"email": {
"type": "string",
"description": "Email address of the Uber user"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
分割したswaggerの各部分を記述できたら、nodeプログラムを使用してjsonを結合します。
下記のようにresolv.jsファイルを作成します。
//resolv.js
var JsonRefs = require('json-refs');
var root = require('./index.json');
JsonRefs.resolveRefs(root, {filter: ['relative', 'remote']})
.then(function (res) {
console.log(JSON.stringify(res.resolved));
}, function (err) {
console.log(err.stack);
});
resolv.jsではjson-refsを使用し、index.jsonを起点にして各JSONを結合します。
jsファイルが記述できたら、下記手順でswagger.jsonを出力してみましょう。
% cd path/your/split-swagger-directory % npm install json-refs #npmモジュールのインストール % node resolve.js > swagger.json #結合
resolv.jsの出力をswagger.jsonにリダイレクトしています。
swagger.jsonが出力されたらSwagger Editorに貼り付けてみてください。
先ほどと同じようにAPIドキュメントが表示されます。
まとめ
今回はswaggerファイルの分割方法について紹介しました。
とにかく肥大しがちな設定ファイルなので、分割して少しでも管理しやすくしましょう。
