Stoplight Studio×Redocで理想的なAPIリファレンスを作成してみた

はじめに

 RESTful APIとフロントエンドを分離して開発する際、バックエンドチームとフロントエンドチームを繋ぐ役割としてAPIリファレンスが必要になります。今まではエンドポイント、HTTPリクエストメソッド、Input/Outputを記載したExcelで管理していたのですが「脱Excel設計書」の流れを遅かれながら取り入れてモダンなドキュメントの作成を検討しました。

Excel管理の問題点

散々言われてきていますがExcelで作成する設計書のデメリットです。

  • Git管理との相性が悪い(差分が確認できない、マージが困難)
  • 検索性が悪い
  • 重い

これらを解消したドキュメントの作成していきたいと思います。

使用したもの

Stoplight Studio

Stoplight StudioはOpenAPI仕様に基づいたRESTful APIドキュメントをGUIで記述することができます。

以前SwaggerEditerを使用した際にはyamlの記述の手間が多くかかるので導入の壁があったのですが、Stoplight Studioは使いやすいGUIが提供されておりチーム全体への定着もさせることができました。

Web版とMac,Windows,Linux向けのデスクトップアプリが提供されており、今回はWindows版をダウンロードして使用しています。

Redoc

RedocはOpenAPI定義からHTML形式のドキュメントを生成するオープンソースツールです。

前述のStoplight Studioだけでも閲覧性は問題ないのですが、デスクトップアプリを導入していないメンバーもブラウザから手軽にドキュメントを閲覧できるようにHTML形式のドキュメントも生成します。

その他

上記2つ以外に以下のサービスを使用しています。

  • AWS S3(Redocで生成したHTMLのホスティング)
  • AWS CodePipeline(Redocを実行)
  • GitLab(Stoplight Studioで生成するドキュメントの管理)

全体構成

全体の構成としては以下のイメージです。

CI/CDには普段使用しているAWS CodePipelineを使用しています。

実際に使ってみた

1.OpenAPIドキュメントを作る

まずStoplight Studioで簡単なAPIドキュメントを作ります。

yamlで200行程度になっていますが、GUIでポチポチするだけで簡単に作成できます。

Stoplight StudioにPrismが組み込まれているため、モックサーバ機能も設定なしで使用できます。

個人的に一番使っている機能が[Try it]タブです。

CurlをGUIからいい感じに実行できます。必要なパラメータもフォーム化されておりリクエストの組み立ても簡単です。

2.Redocでhtmlに変換

OpenAPIドキュメントはyamlなのでそのままでは人間が読むには少し辛い形式になっています。

そのためStoplight Studioで作成&表示をしていたのですが、「ドキュメント読むだけなのに専用アプリ入れるの面倒…」という方のためにhtml形式のドキュメントも生成します。

nodeが実行可能な環境であればどこでも実行できるため、手間を減らすためCIに組み込みたいと思います。

実行環境

使用サービス:AWS CodeBuild

OS:Amazon Linux2(node14実行可能環境として)

CodeBuildの詳しい設定方法は割愛しますが、AWS CodeBuildの場合はbuildフェーズでRedocをインストールして実行可能です。

version: 0.2

phases:
  pre_build:
    commands:
      - echo ${CODEBUILD_SRC_DIR}
  build:
    commands:
      //Redocのインストール
      - npm install -g redoc-cli
      //Htmlドキュメントの生成
      - redoc-cli bundle ${CODEBUILD_SRC_DIR}/[yamlのファイル名].yaml
artifacts:
  files:
    - redoc-static.html

実行すると、1つの静的HTMLファイルが生成されます。ブラウザで開くと以下のように見やすいドキュメントが生成されています。

ここで生成した静的HTMLファイルをCodeDeployでAWS S3に配置し、StaticHostingすることでチーム全体からの参照を実現しています。

総評

「誰でも使いやすい」「Gitで管理したい」「標準化されたもの」の条件を満たし、脱Excelドキュメントを実現できました。

Stoplight Studioは使用しやすいGUIが備わっており、メンバーへの浸透も早かったです。また、ドキュメントを参照したいだけのフロントエンドチームにもお手軽に参照できるRedocで生成したドキュメントは好評でした。

今回使用したツールの感想です。

Stoplight Studioのいいところ

  • Gitをサポート(GitHub, GitLab, Azure DevOps,Bitbucket)
  • デスクトップアプリが無料で使える
  • モックサーバ機能内蔵
  • API Console(リクエストを実行)する機能がある

Stoplight Studioの困ったところ

  • 細かいファイル分割に対応していないため、複数人で編集した際のコンフリクト解消が大変
  • 動作が少し重い

Redocのいいところ

  • 出力ファイルはHTMLファイルが1つのみ(静的ホスティング環境で公開可能)
  • CLIで実行可能なため、CI/CDに組み込める

Redocの困ったところ

  • 検索機能が日本語に非対応
  • カスタマイズできる項目が少ない