NestJS+Swagger+Redocで静的サイトを作成

NestJS

NestJS+SwaggerでAPIドキュメントを書いたとして、それを公開するにはNodeJSが動くサーバが必要になります。

でもNodeJSはバックエンドなのでGitHub PagesとかNetlifyで公開ができないわけです。なので、一度static htmlとして変換してしまえばよいわけです。

APIドキュメントをつくるだけならいろいろ方法はあるのですが、NestJSを経由すればドキュメントと実装の差異がなくなるので、メンテナンスが楽になるので自分は採用しています。

Swagger

NestJSとSwaggerの導入は済んでいるものとします。

個人的にはclass-validatorやclass-transformerも必須だと思っているので、これらも導入しておきましょう。

別にSwagger自体は必須ではないと思うのですが、便利だったのでなんとなく導入しました。

main.ts

SwaggerのGitHubでコードが載っていたのでそれをそのまま利用します。

https://github.com/nestjs/swagger/issues/110

ValidationPipeは実装済みですが、不要であれば外してしまっても構いません。

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { ValidationPipe } from '@nestjs/common';
import * as path from 'path';
import { writeFileSync } from 'fs';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  const options = new DocumentBuilder()
    .setTitle('Documents')
    .build();
  const documents = SwaggerModule.createDocument(app, options);
  const outputPath = path.resolve(process.cwd(), 'swagger.json');
  writeFileSync(outputPath, JSON.stringify(documents), { encoding: 'utf8' });
  SwaggerModule.setup('documents', app, documents);
  await app.listen(3000);
}
bootstrap();

こうするとNestJSが更新されるたびにディレクトリにswagger.jsonが自動で生成されます。このJSONはOpen APIのフォーマットに対応しているみたいなので、Swagger以外にもRedocなどでも変換できます。

ちなみにNestJSをホットリロードできる状態で起動するにはyarn start --watchまたはyarn start:devが必要になります。

Redoc-cli

yarnを利用している前提で話を進めます。

yarn add redoc
yarn add redoc-cli

インストールができたら、ビルドしてみます。bundleはdeprecatedになっているのでbuildを使えとのこと。

npx redoc-cli build swagger.json -o index.html

とすれば出力できます。ちなみに直接redoc-cliとやるとコマンドがないと言われました。

複数ファイルに実行

redoc-cliを使ってOpen API jsonファイルから整形されたhtmlを生成

にはこう書いてあるけれど、試していないのでわからない。まあなんとかなるでしょう。

for file in */swagger.json;do redoc-cli bundle -o ${file%swagger.json}index.html $file;done

メモ

なにかに使えるかもしれない備忘録

Swaggerのアレコレ
https://cream-worker.blog.jp/archives/1076313317.html

swagger-merger + ReDoc + DockerでAPIドキュメントを作る
https://qiita.com/masakurapa/items/447b2f1236bc87226cac#swagger-merger