API Documentation+OpenAPI Tool 14年史 2011-2026。WSDL Web Services Description Language (2001 W3C・SOAP用 XML)・WADL Web Application Description Language (Sun 2009 REST用→廃れる)・Swagger (2011年 Tony Tam Reverb・Wordnik社内Tool・REST API Doc Spec)→Swagger 2.0 (2014)→2015年Linux Foundation OpenAPI Initiative寄贈→OpenAPI Specification OAS 3.0 (2017)→OAS 3.1 (2021 JSON Schema 2020-12互換)→OAS 3.2 (2026予定)・Swagger UI (Web Doc Renderer Open Source)+Swagger Editor+Swagger Codegen→OpenAPI Generator (2018 Fork)・SmartBear Software Swagger商用化Tool・Postman+Insomnia→OpenAPI Import/Export対応・RAML RESTful API Modeling Language (MuleSoft 2013→廃れる→OAS吸収)・API Blueprint (Apiary→Oracle 2017→Maintenance)・Stoplight Studio (2016 Stoplight・Visual Editor+Mocking)+Stoplight Elements (Doc UI)→Smartbear 2021年買収・Redocly Redoc (2017 OSS・Three Panel Beautiful UI Doc)+Redocly OpenAPI CLI+Redocly Workflows・Scalar (2024 Scalar.com・Modern Open Source Doc UI・Fast+Beautiful・Stripe Inspired・人気急上昇)・Bump.sh+Apidog (2023 中国 Postman+Stoplight 統合)・Mintlify (2022 Documentation as Code Modern)・Readme.com+Gitbook+Swagger Hub Cloud・FastAPI 内蔵 OpenAPI生成 (2018 Sebastián Ramírez OSS Python)+Pydantic統合・NestJS @nestjs/swagger Decorator・Hono OpenAPI/Zod-OpenAPI・tRPC vs REST・GraphQL: GraphiQL+Apollo Studio+Altair+Banana Cake Pop・gRPC+Buf Schema Registry・AsyncAPI (2017 Event-driven WebSocket+Kafka)・JSON Schema Draft 2020-12・¥0 OSS-¥¥¥¥/月Pro 2026 Scalar+Redocly+Stoplight+Mintlify+Apidog 5強+OpenAPI Spec Standard。
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 などが採用実績を拡大している。
| 主要要素 | 役割 | 代表的な実装 | 主要バージョン |
|---|---|---|---|
| スペック | API の構造・振る舞いを記述 | OpenAPI Specification | 3.0 / 3.1 / 3.2 |
| UI レンダラー | ドキュメントを閲覧可能にする | Swagger UI、Redoc、Scalar | 1.0+ |
| コード生成 | クライアント・サーバーコードを自動生成 | OpenAPI Generator、Swagger Codegen | 2.0+ |
| エディタ | スペック作成・編集 | Swagger Editor、Stoplight Studio | 1.0+ |
| モック | 実装前に API をテスト | Stoplight Mock、Redocly Mock | 1.0+ |
| CI/CD 連携 | スペックのバージョン管理 | Bump.sh、Apidog | 1.0+ |
| ドキュメント管理 | バージョン管理・公開 | Readme.com、GitBook、Mintlify | 1.0+ |
application/json の content を application/json+schema へ統合し、JSON Schema 2020-12 と完全互換化。| 製品 | 主な機能 | 対応 OAS バージョン | 価格帯 | 主要ユーザー |
|---|---|---|---|---|
| Swagger UI | Web ベースのドキュメント表示 | 2.0+ | 無料 | 企業開発者 |
| Redoc | 3 パネル UI | 3.0+ | 無料 | デベロッパーコミュニティ |
| Scalar | モダン UI、テーマカスタマイズ | 3.1+ | 月額 49 USD | スタートアップ |
| Stoplight Studio | ビジュアルエディタ、モック | 3.0+ | 月額 39 USD | API プロダクトマネージャ |
| Mintlify | Documentation as Code、CI/CD |
| 用語 | 目的 | 主な差分 |
|---|---|---|
| WSDL | SOAP API | XML ベース、サービス定義のみ |
| WADL | REST API | Sun 2009、廃止予定 |
| RAML | RESTful API Modeling | MuleSoft 2013、OAS への統合 |
| API Blueprint | Markdown ベース | 2017 以降はメンテナンスのみ |
| GraphQL | クエリ言語 | スキーマは GraphQL SDL、ドキュメントは GraphiQL など |
| AsyncAPI | イベント駆動 | WebSocket/Kafka 向け、OAS とは別 |
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 年以降は、ドキュメントをコードと同一リポジトリで管理し、継続的に更新するワークフローが主流化。選択肢は多いが、スペック互換性、パフォーマンス、エコシステムの統合度を総合的に評価することが成功の鍵となる。
| 3.1+ |
| 月額 29 USD |
| DevOps チーム |
| OpenAPI Generator | コード生成 | 3.0+ | 無料 | バックエンド開発 |
| Postman | API テスト、インポート/エクスポート | 3.1+ | 無料 / 月額 12 USD | QA エンジニア |
| Insomnia | API クライアント、モック | 3.1+ | 無料 | フロントエンド開発者 |
| FastAPI | Python で自動生成 | 3.1+ | 無料 | Python エンジニア |
| NestJS @nestjs/swagger | TypeScript デコレータ | 3.1+ | 無料 | Node.js 開発者 |