OpenAPI GeneratorとReDocでAPIを「速く !」「正確に ! 」 実装しよう！

技術情報 ソリューション事業本部 システムエンジニア

こんにちは！ ソリューション事業部の金です。
今回は、案件でフロント側のAPI繋ぎ込みする際に活用した「OpenAPI Generator」と「ReDoc」を紹介いたします。

FEではAPIの通信のために、正確なAPIの仕様を理解する必要があります。
そのためにはBEの方とのコミュニケーションコストが生じます。

例えば、下記のように

ちゃんと実装したと思ったのに、上手く動かない…
インタフェースの型ってこれであっているかな…
また仕様が変わったから、APIの修正しなきゃ…
作成したコードがそれぞれ形が違う…

などの悩みがある方、いらっしゃいませんか…？

（私だけかもしれないですが…）
同じ悩みを持っている方！

API定義書としても活用でき、API自動生成をしてくれる
「OpenAPI Generator」と「ReDoc」を活用してみませんか？

今回の記事を読まれるにあたり、前回弊社ブログでサーバーサイドエンジニアの波多野さんが紹介してくださった内容を参考していただけると理解しやすいと思いますので、こちらの記事も最初にご紹介させていただきます！( ・∇・)/

blog.adglobe.co.jp

OpenAPI Specificationの紹介

「OpenAPI Generator」と「ReDoc」を説明する前に、まず『OpenAPI Specification』を軽くご説明します。

『OpenAPI Specification』は
プログラミング言語に従属されないように、HTTP APIのための標準インタフェースを定義したものです。

以前は、Swagger Specificationとも呼ばれており、Swaggerで作成されてました。
JSON または YAMLで定義することができます。今回のプロジェクト内では YAML形式で作成しました。
また、下記のメーター情報も仕様として指定することができます。

  • APIの経路
  • HTTP メソッド
  • Request（Headerなど）
  • Response Body
  • Request / Response 例のデータ
  • Description ( コメント )

OpenAPI Generatorとは

OpenAPI Generatorは OpenAPI Specificationで作成されたドキュメントを変換するライブラリで、下記のような機能を提供しています。

クライアント側
  • API通信するための関数自動生成
  • API Req / Res に使用されるデータのTypeScriptのタイプ（型）自動生成
  • 例の結果をリターンするStubサーバーコード自動生成
サーバー側
  • 全体的な Server 基盤及びビジネスロジックの自動生成
  • API 基盤のService Class 自動生成

ReDocとは


ReDocはOpenAPI Specファイルを読み込みデプロイしてくれるツールです。

Swagger-UIではなくてなぜReDocなの？

Swagger-UIと似ていて、インストールと使用が簡単だという利点があります。
Swagger-UIのように、ブラウザでの API テストはできませんが、
ReDocはローカル環境で作ったAPIが正しく文書化されたか確認＆テストする際に便利です。

APIがきちんとドキュメント化されることの確認と、読みやすさが重要視される際には、ReDocを使用されるのがオススメです！
今回の場合は、API定義書として使いました。
実際に下の画像のようにHTMLファイルとして作成され、凄く見やすいAPI定義書を作成することができます。

Redoc

OpenAPI Generator と ReDocを活用してみよう

ではここから、実践です！(/・ω・)/

OpenAPI Generator と ReDocを活用してみましょう！

OpenAPI Generatorを活用してみる

1. openapi-generator-cli インストール

OpenAPI Generatorは様々なインストール方法を提供しています。

  • Home-brew / NPM / Docker / CLI

今回の場合は、プロジェクトパッケージで管理するため、NPMでインストールしました。
NPMでインストールする場合、OpenAPI GeneratorはJVMの基に動作するため、事前にJDKのインストールが必要です。

npm install @openapitools/openapi-generator-cli
2. Generator Configファイル作成

Root経路にopenapitools.jsonファイルを生成後、下記の設定コードを作成します。
今回はTypeScriptとAxiosモジュールを使うため、typescript-axios変換方法を採用しました。

もっと詳しい内容は こちら を参照して下さい。

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "6.2.1",
    "generators": {
      "v3.0": {
        /* 変換方法決定 */
        "generatorName": "typescript-axios",
        /* 変換結果ルート */
        "output": "./resources/js/generated/api ",
        /* OpenAPI Specification ファイルのルート */
        "glob": "document/api/root_kim_api.yaml"
      }
    }
  }
}
3. OpenAPI Specificationファイルの作成

Swaggerで提供している公式ドキュメントを活用し、root_kim_api.yaml ファイルを作成します。
Swagger Editorを使用するとブラウザで OpenAPI Specification を作成でき、見本のファイルも提供しています。
しかし今回の場合はReDocを使うため、OpenAPI Specification 作成後、ReDocで確認しましょう！

・root_kim_api.yaml
# root_kim_api.yaml
openapi: 3.0.0
servers:
  - url: "http://localhost:8080/"
info:
    description: |
        KIM-WEB API 仕様書
        # Authentication

        共通リクエストヘッダー:
        ```
        Authorization: Bearer {{jwt}}
        Content-Type: application/json
        ````
        <SecurityDefinitions />

    version: 1.0.0
    title: KIM-WEB API SPEC
    x-logo:
        url: "https://www.adglobe.co.jp/ja/wp-content/themes/2022-adglobe/files/img/common/logo.svg"
        altText: Adglobe inc.

x-tagGroups:
    - name: USER
      tags:
          - account

paths:
    /user:
        $ref: "./USER.yaml"
・USER.yaml
# USER.yaml
post:
    tags:
        - account
    summary: "ユーザ登録"
    description: |
        **USER POST** - ユーザ登録

    operationId: postUser
    requestBody:
        content:
            application/json:
                schema:
                    $ref: "./components/parameters/paramPostUser.yaml"
    responses:
        200:
            description: OK
            content:
                application/json:
                    schema:
                        $ref: "./schemas/response/resDefault.yaml"
        400:
            description: |
                * `E001`
            content:
                application/problem+json:
                    schema:
                        $ref: "./components/response/res400.yaml"
        500:
            description: |
                * `E002`
            content:
                application/problem+json:
                    schema:
                        $ref: "./components/response/res500.yaml"
4. Script 登録 ＆ Generator 実行

下記のコードのように pakage.jsonにスクリプトを登録してコマンドを実行すると、
openapitools.jsonで設定したOutputの経路に変換されたファイルが保存されます。

/* package.json */
{
  "scripts": {
    "kim-test-generate": "openapi-generator-cli generate",
  },
}

/* コマンド 実行 */
npm run kim-test-generate
5. Generatorの変換されたファイル確認

OpenAPI Generatorが変換完了すると、様々なファイルが生成されます。

生成されたファイル構造
  • index.ts : モジュールをまとめてくれるファイル
  • configuration.ts : Axiosモジュールを使うための設定
  • base.ts / common.ts : 共通で使用するモジュールの定義
  • api.ts : APIドキュメントで定義したAPIモジュールを定義 (直接使用するモジュール)

api.tsファイルはAPIドキュメントで作成した内容を基にRequest TypeとそのAPIと通信できるモジュールを提供します。

/* Request Type */
export interface ParamPostUser {
    /**
     * ゲスト携帯番号
     * @type {string}
     * @memberof ParamPostUser
     */
    tel: string;
    /**
     *
     * @type {UserType}
     * @memberof ParamPostUser
     */
    userType: UserType;
}

/* API 通信モジュール */
/**
 * AccountApi - object-oriented interface
 * @export
 * @class AccountApi
 * @extends {BaseAPI}
 */
export class AccountApi extends BaseAPI {
    /**
     * **USER POST** - ユーザ登録  **利用シーン** - ユーザーの新規登録
     * @summary ユーザ登録
     * @param {ParamPostUser} [paramPostUser]
     * @param {*} [options] Override http request option.
     * @throws {RequiredError}
     * @memberof AccountApi
     */
    public postUser(
        paramPostUser?: ParamPostUser,
        options?: AxiosRequestConfig
    ) {
        return AccountApiFp(this.configuration)
            .postUser(paramPostUser, options)
            .then((request) => request(this.axios, this.basePath));
    }
}

ReDocを活用してみる

では早速、作ったroot_kim_api.yaml ファイルをUI化して確認しましょう！

1. openapi-generator-cli インストール

ReDocもOpenAPI Generatorのインストールと同じようにNPMでインストールしましょう。

npm -i g redoc-cli
2. ReDocで生成された Web ページ確認

今回はローカル環境で実装したため、
redoc-cli serve を使用して生成されたページを確認できます。

redoc-cli serve ../document/api/root_kim_api.yaml

静的にHTML生成したい場合は、redoc-cli budle を使うと redoc-static.htmlのHTMLファイルが生成されます。

redoc-cli bundle  ../document/api/root_kim_api.yaml

ReDocで生成されたページ（HTML）

root_kim_api.yaml

USER.yaml

最後に

今回はプロジェクトで活用できた OpenAPI Generator と ReDocを紹介いたしました。
OpenAPI GeneratorとReDocの導入を通して、定型化された実装コードを自動生成や見やすいAPI定義書の提供などの OpenAPI 利点を感じました。
非常に便利でしたので、これからも積極的に活用しようと思っています。
こちらの記事を読んで興味が湧いた方は是非活用してみてください！

今後も便利なライブラリがあれば共有したいと思っています。
最後までお読みいただきありがとうございました！('ω')/