はじめに
APIを開発していると、ドキュメント作成って地味に面倒なんですよね。Swaggerで自動生成はできるものの、正直なところ見た目がちょっと古臭いというか、もう少しモダンな感じにできないかなと思うことがあります。
そんな時に見つけたのが「Scalar」というツールです。OpenAPI/Swaggerファイルから、かなり見栄えの良いAPIドキュメントを自動生成してくれます。しかもPostmanの代替になるAPIクライアント機能まで付いているという、なかなか優秀なやつです。
Scalarとは
ScalarはオープンソースのAPIプラットフォームで、主に以下の機能を提供しています。
- APIリファレンス生成: OpenAPI/Swaggerから美しいドキュメントを自動生成
- APIクライアント: オフラインでも使えるPostman代替
- モックサーバー: OpenAPIからモックAPIを自動生成
GitHubで13,000以上のスターを獲得していて、Supabase、GitBook、Tailscaleなど、スタートアップから大企業まで幅広く採用されています。MITライセンスなので、商用利用も問題ありません。
特徴・メリット
1. 見た目がモダン
これ、意外と重要なポイントだと思います。APIドキュメントって社外に公開することも多いので、見た目が良いに越したことはないんですよね。Scalarは最初からデザインが洗練されていて、カスタマイズも柔軟にできます。
2. インタラクティブなテスト機能
ドキュメント上で直接APIを叩けるのは便利です。クライアントを別途起動する手間が省けるので、開発者の体験としてはかなり良いと思います。
3. 30以上のフレームワークに対応
Express、FastAPI、Laravel、Next.js、Nuxt、Django、ASP.NET Coreなど、主要なフレームワークにはほぼ対応しています。自分の技術スタックに合わせて導入できるのはありがたいですね。
4. 複数言語のコード例を自動生成
APIのリクエスト例をJavaScript、Python、cURLなど複数の言語で自動生成してくれます。これ、手動でやると結構な工数になるので、時短になります。
インストール方法
CDN経由（最も手軽）
HTMLファイル1つで始められます。
<!DOCTYPE html>
<html>
<head>
<title>API Reference</title>
<meta charset="utf-8" />
</head>
<body>
<div id="app"></div>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
<script>
Scalar.createApiReference('#app', {
url: 'https://your-api.com/openapi.json',
})
</script>
</body>
</html>
npmパッケージ
npm install @scalar/api-reference
React向け
npm install @scalar/api-reference-react
Vue向け
npm install @scalar/api-reference
基本的な使い方
Reactでの実装例
import { ApiReference } from '@scalar/api-reference-react'
import '@scalar/api-reference-react/style.css'
function App() {
return (
<ApiReference
configuration={{
url: 'https://your-api.com/openapi.json',
theme: 'purple',
}}
/>
)
}
export default App
Expressとの統合
import express from 'express'
import { apiReference } from '@scalar/express-api-reference'
const app = express()
app.use(
'/reference',
apiReference({
url: '/openapi.json',
theme: 'kepler',
})
)
app.listen(3000)
FastAPIとの統合
FastAPIを使っている場合は、デフォルトのSwagger UIをScalarに置き換えることができます。
from fastapi import FastAPI
from scalar_fastapi import get_scalar_api_reference
app = FastAPI()
@app.get("/scalar", include_in_schema=False)
async def scalar_html():
return get_scalar_api_reference(
openapi_url="/openapi.json",
title="API Reference"
)
テーマのカスタマイズ
Scalar.createApiReference('#app', {
url: 'https://your-api.com/openapi.json',
theme: 'purple', // kepler, mars, saturn, moon など
customCss: `
.scalar-app {
--scalar-color-1: #your-brand-color;
}
`,
})
実践的なユースケース
ケース1: 社内APIドキュメントの整備
個人的には、まず社内向けのAPIドキュメントに導入するのがおすすめです。OpenAPIファイルさえあれば、ものの数分で見栄えの良いドキュメントが完成します。新しいメンバーのオンボーディング時間を削減できるのは大きいですね。
ケース2: 外部公開API用のドキュメント
SaaS製品などで外部にAPIを公開している場合、ドキュメントの品質はそのままサービスの印象に直結します。Scalarならブランドカラーに合わせたカスタマイズも簡単にできるので、コスパ的にかなり優秀だと思います。
ケース3: Postmanの代替として
チームでPostmanを使っているけど、ライセンス費用が気になるという話はよく聞きます。Scalarのクライアント機能はオフラインで動作し、環境変数もサポートしているので、基本的な用途なら十分代替になります。
ケース4: モックサーバーとしての利用
フロントエンドとバックエンドを並行開発する際、OpenAPIファイルからモックサーバーを立てられるのは便利です。CLIツールも用意されているので、CI/CDパイプラインに組み込むこともできます。
npx @scalar/cli serve ./openapi.json --port 3000
まとめ
ScalarはOpenAPI/Swaggerベースのプロジェクトなら導入を検討する価値があると思います。
特に良いと感じたポイント:
- 見た目がモダンで、カスタマイズ性が高い
- 30以上のフレームワークに対応している
- MITライセンスで商用利用も問題なし
- APIクライアント、モックサーバーなど周辺ツールも充実
正直なところ、Swagger UIのデフォルトデザインに不満を感じていた人にとっては、Scalarは一択ですね。導入も簡単なので、まずはCDN経由で試してみることをおすすめします。