InfinityのAPI仕様書自動生成メカニズム
Infinityは、高スループットかつ低レイテンシを特徴とするベクトル埋め込み提供のためのREST APIサーバーです。本サービスの開発・統合を円滑に進めるために、OpenAPI規格による仕様書の自動生成と可視化が実装されています。以下では、サーバー起動状態を前提とした仕様書取得ワークフローを解説します。
OpenAPI JSONの取得と検証スクリプト
プロジェクト配下には、動作中のInfinityサーバーからリアルタイムでAPI定義ファイルを取得するシェルスクリプトが配置されています。この仕組みは、手動でのコピー貼り付けに依存せず、環境差異を最小限に抑えることを目的としています。
標準的な生成処理は以下の手順で実行されます。
- Infinityデーモンが正常に稼働していることを確認
- 仕様書取得スクリプトの実行
- 出力先ディレクトリへの保存とJSON形式検証
基本的な実装をより堅牢なバッチ処理に書き換えた例を示します。
#!/usr/bin/env bash
set -euo pipefail
TARGET_HOST="127.0.0.1"
SERVICE_PORT=7997
OUTPUT_DIR="./spec_assets"
SPEC_FILE="${OUTPUT_DIR}/api_definition.json"
mkdir -p "${OUTPUT_DIR}"
echo "Checking Infinity service availability at ${TARGET_HOST}:${SERVICE_PORT}..."
if ! curl -s -o /dev/null -w "%{http_code}" "http://${TARGET_HOST}:${SERVICE_PORT}/health" | grep -q "200"; then
echo "Error: Service is unreachable. Ensure Infinity is running."
exit 1
fi
echo "Fetching OpenAPI specification..."
wget -qO "${SPEC_FILE}" "http://${TARGET_HOST}:${SERVICE_PORT}/openapi.json"
# Basic validation using jq (optional but recommended)
if command -v jq &> /dev/null; then
jq empty "${SPEC_FILE}" && echo "Successfully saved and validated OpenAPI spec." || exit 1
fiこのアプローチにより、稼働中のインスタンスが持つ最新のルーティング情報やスキーマ定義を確実に取得できます。
Swagger UIによるインタラクティブなドキュメント閲覧
生成されたOpenAPI定義は、自動的にSwagger UIコンポーネントと連携し、ブラウザ上で直感的なAPI探索環境を提供します。Infinityサーバー起動時に、ルートパスの `/docs` エンドポイント経由でこのインターフェースにアクセス可能です。
標準の動作ポートが `7997` の場合、以下のURLで起動します。
http://localhost:7997/docsこのダッシュボードでは、以下の開発支援機能が標準で利用できます。
- 全エンドポイントの階層的表示とメソッド別フィルタリング
- リクエストペイロードのスキーマ定義と必須フィールドの明示
- Try it out機能を用いたリアルタイムAPI呼び出しとレスポンス確認
- 認証スキーマ（APIキーまたはBearerトークン）の設定ダイアログ
UI上でのテスト実行結果は、ネットワークタブの代わりに直接表示されるため、デバッグ時の情報フローが大幅に短縮されます。
型安全クライアントライブラリの自動生成
ドキュメント閲覧だけでなく、OpenAPI定義はコード生成エンジンの入力データとしても活用されます。Python環境を対象としたクライアントSDKの生成ワークフローは、以下のスクリプトを介して実行します。
import subprocess
import sys
from pathlib import Path
def bootstrap_api_sdk(spec_path: Path, dest_root: Path):
if not spec_path.exists():
raise FileNotFoundError(f"OpenAPI definition not found at {spec_path}")
command = [
"openapi-python-client", "generate",
"--output-dir", str(dest_root),
"--path", str(spec_path),
"--meta", "generated"
]
print(f"Generating client SDK from {spec_path}...")
result = subprocess.run(command, capture_output=True, text=True)
if result.returncode != 0:
print(f"Generation failed: {result.stderr}", file=sys.stderr)
sys.exit(1)
print("SDK generation completed successfully.")
if __name__ == "__main__":
bootstrap_api_sdk(Path("./spec_assets/api_definition.json"), Path("./sdk_output"))この処理により、エンドポイントごとに最適化された同期・非同期クライアントクラス、データモデル、例外ハンドリング構造が自動的に構築されます。手動でHTTPリクエストを構築する際の型不一致やパラメータ順序のミスを防ぎ、アプリケーション層での保守性を向上させます。
仕様書の継続的保守とCI/CD統合
APIの進化に伴い、ドキュメントと実装の乖離を防ぐことは不可欠です。Infinityのワークフローでは、仕様書の更新をパイプラインの自動化手順に組み込むことを推奨しています。
- ビルドステージにおけるスクリプト実行により、最新の実装状態を常に仕様書に反映
- タグ付バージョンリリース時に、ドキュメントアーティファクトの自動アップロード
- Snapshots環境へのデプロイ直後、Swagger UI経由のSmoke Testを自動化