[MavsDiary #4]AmplifyでAPIドキュメントをデプロイする方法

マーベリックスでは定期的に社内勉強会を開催しており、
今回はその内容の一部をご紹介します！

こちらの勉強会でお話しした、APIドキュメントをコード管理した取り組みですが、
具体的な設定例を紹介します！

勉強会の様子はこちらから
マブスバックエンドMTG#2 – APIドキュメントを活用した話

どうしたいか

このように、mainブランチへマージされたタイミングで、
コード内に書き込んだリクエスト・レスポンスの情報をもとに、
APIドキュメントを生成しデプロイします。

各ユーザーは指定のURLへアクセスし、最新のAPI使用を把握して開発可能な運用を行うことを目指します！

実行する環境を構築する

各バージョン

node.js16.8.0Express.js4.17.12TypeScript4.9.3APIDoc0.53.1

設定ファイルを設置する

ドキュメント共有の項目を設定するため、
プロジェクト直下にapidoc.jsonを作成し、下記の内容を設定します。

{
  "name": "サンプルプロジェクト",
  "version": "1.0.0",
  "description": "サンプルプロジェクトAPI仕様書",
  "title": "サンプルプロジェクトAPI仕様書",
  "url": "https://localhost:3000"
}

また、yarnコマンドでジェネレートできるようにpackage.jsonにコマンドを追加しておくと便利です。

"scripts": {
    ~~~~~~~~~~,
    "apiDoc-generate": "node_modules/.bin/apidoc -i src -o docs -c apidoc.json"
  },

コードにAPIドキュメント用のコメントを作成する

ツールはAPIDocというRestAPI用のドキュメントジェネレータを使用します。
インストール方法などは公式を参考にしてください！

"@"のプレフィックスをつけた各項目にAPIの設定値を記載していきます。

/**
 * @api {get} /sample-api サンプルAPI
 * @apiVersion 1.0.0
 * @apiGroup common
 * @apiPermission admin
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
router.get(
  '/sample-api',
  (req: Request, res: Response, next: NextFunction) => {
    // ~~~~~~~~~
  }
);

代表的な設定項目を紹介します。

@api {get} /sample サンプルAPIHTTPメソッド、API名を記載します。@apiVersionエンドポイントのバージョンを記載します。@apiGroup画面毎やドメイン毎などアプリケーションのルールに従ってグループ名を記載します。@apiPermission実行権限を記載します。アプリケーションで決まったロール名や権限などを記載します。@apiSuccessExample正常終了時のレスポンス例を記載します。@apiErrorException発生時に起こり得るエラーを記載します。@apiErrorExampleエラー終了時のレスポンス例を記載します。

このように各APIの先頭で設定することで別ツールでのドキュメント管理を回避することができます！

ローカル環境でドキュメントをジェネレートする

コメントで書くところまで進めたら、まずはローカル環境でジェネレートしてみましょう。
下記コマンドを実行し、プロジェクト直下のdocsフォルダへドキュメントを吐き出します。

node_modules/.bin/apidoc -i src -o docs -c apidoc.json

node_modules内のbinにジェネレートに必要なコマンドが用意されているので、
そちらを使用します。

-iinputするソースの場所を指定します。例では、src配下のソースを対象に前述で定義した設置値が読み込まれます。-oジェネレートしたドキュメントが吐き出される場所を指定します。例では、docs配下に吐き出されます。

問題無くジェネレートが完了すると、指定したdocs配下にjsなどのファイルが入ります。

警告やエラーが出る場合

APIDocはとても親切にどこ場所で記載エラーがあるのかを教えてくれます。

{"message":"parser plugin 'description' not found in block: 11 in file: src/routes/sample/hogehoge.ts","level":"warn"}

のようにコンソール状に表示されるため、
ジェネレートに失敗している場合はエラーを直して再度実行してみてください！

メンバーへ共有する環境を構築する

ローカルでのジェネレートが成功したら、ホスティングサービスへデプロイしてみましょう！
今回はAWS Amplifyでデプロイします。

⚠️アプリケーションを稼働させているIaaSに合わせたホスティングサービスの方がメンテしやすく、使い勝手が良いです。

AmplifyとGithubを連携させる

mainブランチへマージされたタイミングでジェネレートを開始するために、
Githubと連携させます。

▲Githubを選択します。

▲リポジトリと接続します。

▲モノレポで構成している場合は、APIDocが入っているディレクトリを設定します。

今回は下記の構成で作成したプロジェクトをサンプルとしているため、
backendを指定します。

sample
 ∟ frontend
 ∟ backend
   ∟ package.json
   ∟ apidoc.json
   ∟ ・・・・

⚠️プロジェクト内がバックエンドのみであれば空白で大丈夫です！

▲amplify.ymlに構築する設定を記載します。

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - yarn install --production=false
        build:
          commands:
            - yarn run apiDoc-generate
      artifacts:
        baseDirectory: /docs
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
    appRoot: backend

このようにbuildコマンド、参照ディレクトリを設定します。

⚠️注意1