🐈

OpenAPIとSwaggerとRedocの違いと関係性について説明

2024/01/11に公開

OpenAPIとは？

OpenAPI（以前のSwagger Specification）は、RESTful APIのための仕様（規格）です。
これは、APIの機能を記述するための標準的な方法を提供します。

標準化された記述形式:
OpenAPIは、APIがどのように動作するかを記述するための一般的な方法を提供します。
これにより、異なる開発者やツールがAPIを簡単に理解し、利用できるようになります。
言語に依存しない:
OpenAPI仕様は特定のプログラミング言語に依存しないため、どんな言語で書かれたAPIにも使用できます。
ドキュメントとコードの整合性:
OpenAPIを使用すると、APIのドキュメントと実際のコードの間で整合性を保ちやすくなります。

Swaggerは、Web APIの設計、構築、ドキュメント化、および消費（使用）を容易にするツールのセットです。
もともとは独立したプロジェクトでしたが、OpenAPI Initiativeの一部となりました。

APIの設計:
Swaggerを使用すると、APIがどのように動作するかを視覚的に設計できます。
つまり、どんなデータを送受信するか、どのような機能があるかを定義できます。
自動ドキュメント生成:
APIの仕様を書くと、Swaggerツールがそれを読み取り、人が理解しやすい形式のドキュメントを自動的に生成します。
コード生成:
Swaggerを使えば、APIの仕様に基づいてサーバーやクライアントのコードを自動生成することができます。

Redocは、OpenAPI（Swagger）仕様を基にして、APIのドキュメントを生成するためのツールです。
Redocは、特にAPIドキュメントの視覚的な表現に重点を置いており、クリーンで読みやすいドキュメントを生成します。

美観とユーザビリティに注力したドキュメント表示:
RedocはOpenAPI仕様に基づいて作成されたAPIドキュメントを、クリーンで読みやすい形式で表示します。
これにより、エンドユーザーや開発者がAPIの機能をより簡単に理解できます。
インタラクティブではない静的ドキュメント提供:
Redocはインタラクティブな操作を提供せず、APIの詳細な説明と構造を静的なページとして表示します。
これはAPIのドキュメントを閲覧するための、よりシンプルで直感的なアプローチを提供します。
カスタマイズ可能なデザイン:
Redocはカスタマイズ可能なテーマやレイアウトをサポートしており、特定のブランドやデザインガイドラインに合わせてドキュメントの外観を調整することが可能です。

これらはすべて連携して動作します。
OpenAPIはAPIの構造を定義する基準を提供し、Swaggerツールはその仕様を基にAPIを設計・テストし、RedocはそのAPIドキュメントを美しく表示します。

簡単に言うと、
OpenAPIは「APIの設計ルール」、
Swaggerは「そのルールに基づいてAPIを作るツール」、
Redocは「作られたAPIのドキュメントをキレイに見せるツール」
と考えることができます。