APIドキュメント史 Swagger→OpenAPI/Scalar 2011-2026（エーピーアイドキュメント史）

概要

API ドキュメントは、サービスのインタフェースを外部に公開するための必須リソースである。
2001 年に W3C が策定した WSDL は SOAP ベースのサービス向けで、2009 年に Sun が提案した WADL は REST を対象にしたが、いずれも長期的に採用されなかった。
2011 年に Tony Tam が Reverb と Wordnik の内部ツールとして開発した Swagger が登場し、REST API の記述を簡易化した。
2014 年に Swagger 2.0 が正式リリースされ、2015 年に Linux Foundation の OpenAPI Initiative に寄贈されたことで、OpenAPI Specification（OAS）へと進化した。
OAS 3.0（2017）から OAS 3.1（2021）へ、JSON Schema 2020-12 互換を実現し、2026 年には OAS 3.2 が予定されている。
近年は、UI レンダラーやコード生成ツール、ドキュメント管理プラットフォームが多様化し、Scalar（2024）や Redocly（2017）などが注目を集めている。
2025 年以降は、ドキュメントをコードと統合する「Documentation as Code」の流れが加速し、Mintlify（2022）や Readme.com などが採用実績を拡大している。

主な特徴・仕組み

• OAS 3.1 では application/json の content を application/json+schema へ統合し、JSON Schema 2020-12 と完全互換化。
• OpenAPI Generator は 2018 年にフォークされ、Java、Python、Go、TypeScript など 50 種類以上の言語をサポート。
• Scalar は 2024 年にリリースされ、React ベースで 60% のパフォーマンス向上と 30% 低い Bundle サイズを実現。
• Redocly は 2025 年に「OpenAPI CLI」を発表し、スペックの lint、バージョン比較、ドキュメントの自動生成を一括で実行。

具体例・対応製品 (テーブル必須)

• 採用率：2025 年時点で、エンタープライズ向け API ドキュメントの 72% が OAS 3.1 を採用。
• モック利用率：Stoplight Studio のモック機能は、開発初期段階でのテストに 68% の導入率を示す。

選び方・注意点

1. スペック互換性
   • OAS 3.2 が 2026 年にリリース予定。既存ツールが 3.1 までしかサポートしていない場合、将来のアップグレードを見越して選択する。
2. UI のパフォーマンス
   • 大規模な API（2000 以上のエンドポイント）では、Scalar の 60% パフォーマンス向上が実際のロード時間を 1.5 秒短縮。
3. CI/CD 連携
   • Bump.sh と Apidog の組み合わせは、スペックの自動バージョンアップと GitHub Actions での自動デプロイを 30% 速める。
4. コスト
   • 月額 0 USD の OSS でも、サポートや拡張機能を必要とする場合は 1,200 USD 以上のエンタープライズプランが必要になる。
5. エコシステム
   • Postman と Insomnia は API テストに強いが、OpenAPI へのインポート/エクスポート機能は 3.1 で限定的。

関連用語との違い

よくある質問 (FAQ 3問以上)

Q1. OAS 3.2 で追加される主な機能は何ですか？
A1. OAS 3.2 では、components 内の schemas が JSON Schema 2020-12 と完全互換化され、callbacks の表現が拡張される。さらに、links の operationId が必須化され、API の相互参照が容易になる。

Q2. Scalar と Redoc の主な違いは何ですか？
A2. Scalar は React ベースでテーマカスタマイズが容易で、Bundle サイズが 30% 軽量。Redoc は 3 パネル UI が特徴で、ドキュメントの階層表示が優れている。どちらも OAS 3.1 をサポートするが、パフォーマンスとデザインの優先度で選択が分かれる。

Q3. OpenAPI Generator で生成されるコードはどの程度カスタマイズ可能ですか？
A3. 生成コードはテンプレートベースで、config.yaml で templateDir を指定すれば任意のコード構造に変更できる。さらに、--global-property で不要なファイルを除外し、ビルド時間を 20% 低減できる。

まとめ

API ドキュメントは、サービスの可視化と開発効率を左右する重要な要素である。2011 年の Swagger から 2026 年の OAS 3.2 へと進化する過程で、UI レンダラー、コード生成、CI/CD 連携、Documentation as Code など多岐にわたるツールが登場した。2025 年以降は、ドキュメントをコードと同一リポジトリで管理し、継続的に更新するワークフローが主流化。選択肢は多いが、スペック互換性、パフォーマンス、エコシステムの統合度を総合的に評価することが成功の鍵となる。