Posted inDevelopment

さらば、古臭いSwagger UI：Node.jsプロジェクトにScalarを導入するガイド

Development tutorial - IT technology blog
Development tutorial - IT technology blog

実務プロジェクトでSwagger UIを使う際の悩み

日本のクライアント向けに取引管理システムを6ヶ月間開発した際、致命的な問題に気づきました。それはAPIドキュメントです。バックエンド側でコードを丁寧に書き、swagger-jsdocを使って自動化していたにもかかわらず, Swagger UIのデフォルトUIに対してフロントエンドチームやテスターから不満が続出したのです。

問題はデータではなく、ユーザーエクスペリエンス（UX）にありました。Swagger UIはまるで2010年代のウェブサイトのような見た目です。200以上のAPIリストから特定のエンドポイントを探し出すのは、まさに苦行でした。「Try it out」機能はネストされたオブジェクトの扱いに手間取り、返却されるJSONフォーマットもデータ量が多いと非常に読みづらいものでした。

なぜSwagger UIはもはや最良の選択肢ではないのか？

Swagger UIは過去10年間、業界標準でした。しかし、開発者体験（DX）への要求が厳しくなるにつれ、許容しがたい制限が目立つようになりました。

  • 古臭いUI: プロジェクトのブランドイメージに合わせてCSSをカスタマイズするのは非常に複雑です。少しレイアウトをいじっただけで、ページ全体が崩れてしまうこともあります。
  • パフォーマンスの低さ: 10,000行を超えるOpenAPIファイル（JSON/YAML）を読み込むと、ブラウザがフリーズしたり、スクロールがカクついたりすることがよくあります。
  • 貧弱なAPIクライアント機能: 単にリクエストを送るだけです。Postmanのように環境変数を管理したり、トークンをコレクションとして保存したりすることはできません。

私はかつて5万行のコードをリファクタリングしたことがありますが、その時の教訓は「優れたAPIドキュメントは、フロントエンドのAPIモックやロジック説明に費やす会議時間を少なくとも30%削減できる」ということでした。

よくある代替案

Scalarに完全に移行する前に、いくつかの有名なツールを検討しました：

  1. Redoc: プロフェッショナルなUIで、左側のメニュー構成も非常に合理的です。しかし、無料版ではブラウザ上で直接APIテストを行うことができません。
  2. Stoplight Elements: モダンですが、中規模以下のExpress.jsプロジェクトには設定が少し重すぎます。
  3. Postman/Insomnia: これらは外部ツールです。ファイルをエクスポートして手動で共有する必要があるため、コードとドキュメントの間でバージョンの乖離が発生しがちです。これらはAPIの不整合を防ぐ上でも大きな課題となります。

Scalar — APIドキュメントに新たな風を

Scalarは、Redocの美しさとPostmanの利便性を兼ね備えています。このライブラリは軽量で、15以上のプログラミング言語のコードスニペット生成をサポートしており、Node.js互換のREST APIを構築する際にも深く統合されています。

ステップ1：ライブラリのインストール

Express.jsを使用している場合は、Scalarのアダプターパッケージと、API定義をスキャンするためのswagger-jsdocをインストールします：

npm install @scalar/express-api-reference swagger-jsdoc

ステップ2：OpenAPI仕様の設定

app.jsファイルで、以下のようにAPIの基本情報を定義します：

const swaggerJsdoc = require('swagger-jsdoc');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Node.js APIプロジェクト',
      version: '1.0.0',
      description: 'Scalarを使用したAPIドキュメント',
    },
    servers: [{ url: 'http://localhost:3000' }],
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(swaggerOptions);

ステップ3：Scalarミドルウェアの統合

swagger-ui-expressの代わりに、わずか数行のコードでScalarに置き換えることができます：

const express = require('express');
const { apiReference } = require('@scalar/express-api-reference');
const app = express();

app.use(
  '/docs',
  apiReference({
    spec: { content: specs },
  }),
);

app.listen(3000, () => {
  console.log('APIドキュメントのURL: http://localhost:3000/docs');
});

6ヶ月間使用した後の実際の感想

Scalarの最大の魅力は、統合されたAPIクライアントです。エンドポイントを開くと、右側にPostmanそっくりのリクエストシミュレーターが表示されます。Node.js、Python、Goなどの言語を選択して、サンプルコードを即座にコピーして利用できます。

一瞬でテーマをカスタマイズ

Scalarは、設定を1行追加するだけでテーマを変更できます。GitHub風やSolarized風が好みなら、themeプロパティを追加するだけです：

apiReference({
  theme: 'purple', // オプション: 'default', 'moon', 'purple', 'solarized'
  spec: { content: specs },
})

ショートカットキーによる超高速検索

Ctrl + Kのショートカットは、大規模プロジェクトにおける救世主です。グローバル検索バーが開き、マウスでスクロールすることなく、目的のエンドポイントへ一瞬でジャンプできます。

実務からのちょっとした注意点

正直なところ、Scalarに移行した当初は、非常に深い階層のオブジェクトで表示エラーが発生することがありました。しかし、開発チームはGitHubでのIssue対応が非常に速く、通常はその週のうちに修正パッチがリリースされます。

NestJSを使用している場合も、Scalarには専用の統合パッケージが用意されています。securitySchemesを適切に設定して、Bearerトークンの入力欄がプロフェッショナルに表示されるようにするのを忘れないでください。

結論として、Swagger UIの古臭いUIに飽き飽きしているなら、Scalarは今最も価値のあるアップグレードの選択肢です。ドキュメントを美しくするだけでなく、プロジェクト拡大時の「スパゲッティコード」脱却術と併せて検討することで、チーム全体の作業スピードを確実に向上させてくれます。

Share:
Tags: