メインコンテンツへスキップ
見出し画像

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.yaml

    specs/paths/index.yaml
    すべてのAPIエンドポイントの参照をまとめるファイルです。
    各APIインターフェースの定義は、個別のYAMLファイルに記載されます。

    /user/{id}:
      $ref: ./user.id.yaml

    specs/definitions/index.yaml
    すべてのモデルへの参照をまとめるファイルです。
    各モデルの定義は、個別のYAMLファイルに記載されます。

    User:
      $ref: ./user.yaml

    specs/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: string

    spec.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ライブラリを組み合わせることにより、開発中は論理的に分割されたファイルを扱い、コード生成の際には単一の統合された定義ファイルを使用することが可能です。

    私たちの会社では、今回ご紹介したような開発効率を向上させるための取り組みを、日々探求し続けています。
    ご連絡をお待ちしています!

    あなたへのおすすめ