要約

Openapi仕様で書かれたYamlファイルは、ツールを使って静的なHTMLに変換することができる。ここでは、それらのツールのひとつであるredocで、YamlをHTMLに変換する。通常は、手元でredocを使い、HTMLに変換したのち、関係者に共有したり、S3の静的ホスティング機能を使って共有したりする。本稿では、手元で変換する手間を惜しむため、CodeCommitにコミットしたら、自動的にHTMLに変換し、S3にホストする仕組みを紹介する。

構成

手順

１． CodeCommitのリポジトリを準備する

下記のように、buildspec.ymlとopenapi.yamlを用意する。buildspecには、codebuildで実行する処理を記述する。
openapiはAPI仕様である。

２．buildspec.ymlを用意する

以下のようなbuildspec.ymlを用意する。
nodejsのバージョン14のコンテナを使用している。まずredocツールを導入し、そのあと、openapi.yamlをHTMLに変換し、変換後のHTMLファイルをリネームしている。

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 14
    commands:
      - npm install -g redoc-cli
  pre_build:
    commands:
      - echo Nothing to do in the pre_build phase...
  build:
    commands:
      - echo Build started on `date`
      - redoc-cli bundle openapi.yaml
      - mv redoc-static.html openapi.html
  post_build:
    commands:
      - echo Build completed on `date`
artifacts:
  files:
    - openapi.html

３． HTMLをホストするS3を用意する

静的ホスティングを有効にしたS3を用意する。

４．CodeBuildプロジェクトを作成する

ソースプロバイダにCodeCommitを指定、１で作成したリポジトリを指定。

環境はマネージドイメージを使用し、Buildspecは、buildspecファイルを使用するを選択（これにより、リポジトリのbuildspec.ymlが自動的に使用される）。
このとき、OSにAmazonLinuxを選択すると、SRC_DIRのダウンロードに失敗したというエラーが発生したため、それを回避すべく、Ubuntuを選択した（Ubuntuだとなぜうまくいくのかは不明・・・）。

アーティファクトをS3（３で作成したもの）に設定。アーティファクトの暗号化を削除を選択しておくこと（選択しない場合、ファイルを正常に閲覧できない）。

５． CodePipelineを構築する

sourceにCodeCommitの１で作ったリポジトリを指定する。

ビルドステージを追加する、で４で作成したCodeBuildプロジェクトを指定する。

デプロイステージを追加する、で３で作成したS3バケットを指定する。デプロイする前にファイルを抽出するにチェックを入れる。

まとめ

本稿では、Codeシリーズを活用し、CodeCommitにファイルをコミットするだけでHTMLに変換、S3で公開するまでを自動化する方法を紹介した。S3のURLを共有しておくことで、開発者は常に最新のドキュメントを参照することができる。都度HTMLファイルを配布する必要がないため、開発にかかる負担を減らすことができる。