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ファイルが生成されます。ブラウザで開くと以下のように見やすいドキュメントが生成されています。