
OpenAPI 2.0(Swagger)の定義をどのように管理しているか
こんにちは!株式会社フィノバレーでサーバーサイドエンジニアとして働いている諏訪です。
弊社のサーバーチームでは、OpenAPI 2.0(Swagger)を活用したスキーマファーストなアプローチでAPIを開発しています。
APIの仕様と実装を同期させることで、仕様と実装の乖離を防ぐことができるアプローチです。
しかし一方で、APIの数が増加するにつれて、OpenAPIの定義ファイルも肥大化していきます。
実際に、弊社の最終的なOpenAPIの定義ファイルは6万行を超える規模に達しており、これを単一のYAMLファイルで管理することは現実的ではありません。
可読性の低下、差分管理の困難さ、開発体験の著しい悪化は避けられない問題です。
そういった問題を解決するために、この記事ではOpenAPIの定義ファイルを分割し、開発効率と可読性を向上させるための管理方法について記載しています。
さらに、分割されたファイルをビルド時に単一の定義ファイルに結合する具体的なコードも紹介します。
OpenAPI定義ファイルのディレクトリ構成
OpenAPI定義ファイルは以下のようなディレクトリ構成で管理しています。
APIエンドポイントとモデルを明確に分離し、それぞれのindex.yamlで参照元を一元管理するための構造です。
- specs/ # OpenAPI定義のルートディレクトリ
- definitions/ # APIから読み込むモデルを定義
- user.yaml # 例: ユーザーモデルの定義
- index.yaml # モデル名と読み込むファイルを定義
- paths/ # APIエンドポイントの定義
- user.id.yaml # 例: /users/{id}エンドポイントの定義
- index.yaml # APIエンドポイントと読み込むファイルを定義
- index.yaml # OpenAPI定義のルートファイル
- spec.yaml # ビルドされた最終的なOpenAPI定義ファイル各ファイルの役割
specs/index.yaml
このファイルは、OpenAPI定義のルートとなるファイルです。
paths(APIエンドポイント)とdefinitions(モデル)の参照元を定義します。
swagger: "2.0"
info:
description: |
地域通貨プラットフォーム API 仕様
title: Local Currency API
version: 1.0.0
consumes:
- application/json
produces:
- application/json
schemes:
- http
host: localhost
basePath: /api/v1
paths:
$ref: ./paths/index.yaml
definitions:
$ref: ./definitions/index.yamlspecs/paths/index.yaml
すべてのAPIエンドポイントの参照をまとめるファイルです。
各APIインターフェースの定義は、個別のYAMLファイルに記載されます。
/user/{id}:
$ref: ./user.id.yamlspecs/definitions/index.yaml
すべてのモデルへの参照をまとめるファイルです。
各モデルの定義は、個別のYAMLファイルに記載されます。
User:
$ref: ./user.yamlspecs/paths/*.yaml(例: user.id.yaml)
具体的なAPIインターフェースを記載するファイルです。
get:
summary: ユーザー取得API
description: |
## 説明
ユーザーの詳細を取得するためのAPI。
## 使用可能ユーザー
| 匿名ユーザー | Payユーザー | Pay+ユーザー | Bankユーザー | 加盟店ユーザー | 金融機関ユーザー | 行政機関ユーザー |
| --- | --- | --- | --- | --- | --- | --- |
| - | - | - | - | - | ○ | - |
operationId: fetchUser
tags:
- users
parameters:
- name: id
in: path
description: ユーザーID
required: true
type: integer
format: int64
responses:
200:
description: OK
schema:
$ref: "#/definitions/User"
default:
description: unexpected error
schema:
$ref: "#/definitions/Error"specs/definitions/*.yaml(例: user.yaml)
具体的なモデルの定義を記載するファイルです。
description: ユーザー情報
type: object
required:
- name
properties:
name:
description: ユーザー名
type: stringspec.yaml
分割されたAPIエンドポイント、モデルの定義がまとまったファイルです。
後述するコマンドでファイルが生成されます。
弊社はspec.yamlを元にAPIサーバーのHTTPハンドラーを生成するアプローチを取っています。
使用しているツールはgo-swaggerです。
分割されたYAMLファイルを結合する
弊社ではサービスリリース当初に作成したbuild.jsをコマンドで呼び出し、分割されたYAMLファイルを結合しています。
(build.jsの作成日が8年前でパッケージも古くなっているため、そろそろメンテナンスしないと駄目ですね…。)
分割されたYAMLファイルを結合するために、json-refsというライブラリを使用しています。
このライブラリのおかげで、$refを使って参照している外部ファイルを再帰的に解決し、単一のYAML構造にまとめることができます。
build.js
#!/usr/bin/env node
'use strict';
var resolve = require('json-refs').resolveRefs; // json-refsのインポート
var YAML = require('js-yaml'); // YAMLパーサーのインポート
var fs = require('fs'); // ファイルシステムモジュールのインポート
var program = require('commander'); // コマンドライン引数パーサーのインポート(オプション)
program
.version('1.0.0')
.usage('<yaml file ...>')
.parse(process.argv);
// コマンドライン引数から入力ファイル名を取得
var file = program.args[0];
if (!fs.existsSync(file)) {
console.error('File does not exist. ('+file+')');
process.exit(1);
}
// ルートYAMLファイルを読み込んでオブジェクトに変換
var root = YAML.safeLoad(fs.readFileSync(file).toString());
var options = {
filter : ['relative', 'remote'],
loaderOptions : {
processContent : function (res, callback) {
// 参照先のファイル内容を読み込み、YAMLとしてパースするカスタムローダー
callback(null, YAML.safeLoad(res.text));
}
}
};
resolve(root, options).then(function (results) {
// 解決されたオブジェクトをYAML形式で出力
console.log(YAML.safeDump(results.resolved, {'lineWidth': 200}));
});ビルドコマンド
このbuild.jsスクリプトを使って、分割されたYAMLファイルを結合するには以下のコマンドを実行します。
cd ./specs && ../build.js index.yaml > ../spec.yamlこのコマンドを実行すると、specs/index.yamlをルートとしてすべての$ref参照が解決され、結果として単一のspec.yamlファイルが生成されます。
まとめ
OpenAPIの定義ファイルを分割して管理することで、中〜大規模なAPI開発における可読性、メンテナンス性、チーム開発の効率を大幅に向上させることができます。
$refとjson-refsライブラリを組み合わせることにより、開発中は論理的に分割されたファイルを扱い、コード生成の際には単一の統合された定義ファイルを使用することが可能です。
私たちの会社では、今回ご紹介したような開発効率を向上させるための取り組みを、日々探求し続けています。
ご連絡をお待ちしています!