FastAPIとOpenAPI
FastAPIは、Pythonの高速（高性能）、Webフレームワークで、APIの構築に最適です。FastAPIは、Python 3.6以降の型ヒントを使用してAPIパラメータを宣言します。これにより、エディタのサポート（補完、型チェックなど）が強化され、直感的なAPIドキュメンテーションとデータ検証が可能になります。
OpenAPIは、RESTful APIの定義とドキュメンテーションを作成するための仕様です。FastAPIは、OpenAPIを使用して自動的にAPIドキュメンテーションを生成します。これにより、APIのエンドポイント、リクエストボディ、パラメータ、レスポンスなどの詳細を視覚的に理解し、対話的に操作することができます。
FastAPIとOpenAPIの組み合わせは、開発者が高品質なAPIを迅速に開発し、そのドキュメンテーションを簡単に管理できるようにします。これにより、APIの利用者は、APIの使用方法を容易に理解し、その機能を最大限に活用することができます。
SwaggerとReDocの表示
FastAPIは、OpenAPIに基づいてAPIドキュメンテーションを自動的に生成します。このドキュメンテーションは、Swagger UIとReDocという2つの異なる形式で表示できます。
Swagger UIは、APIのエンドポイント、リクエストボディ、パラメータ、レスポンスなどの詳細を視覚的に理解し、対話的に操作することができます。Swagger UIは、APIのテストとデバッグに非常に便利です。
一方、ReDocは、より詳細なドキュメンテーションと高度な機能を提供します。ReDocは、APIの全体的な構造を視覚化し、各エンドポイントの詳細な説明を提供します。また、ReDocは、APIのバージョン管理や複数のAPIの統合に対応しています。
FastAPIを使用すると、これらのドキュメンテーションツールを簡単に設定し、カスタマイズすることができます。これにより、開発者はAPIのドキュメンテーションを効率的に管理し、APIの利用者はAPIの使用方法を容易に理解することができます。これは、APIの開発と利用の両方を効率化し、生産性を向上させます。
URLの変更方法
FastAPIでは、Swagger UIとReDocのドキュメンテーションはデフォルトでそれぞれ /docs と /redoc のURLでアクセスできます。しかし、これらのURLはカスタマイズ可能です。
FastAPIのインスタンスを作成する際に、docs_url と redoc_url のパラメータを設定することで、Swagger UIとReDocのURLを変更することができます。
以下に、Swagger UIとReDocのURLをそれぞれ /documentation と /reference に変更する例を示します。
from fastapi import FastAPI
app = FastAPI(docs_url="/documentation", redoc_url="/reference")
この設定により、Swagger UIは http://localhost:8000/documentation で、ReDocは http://localhost:8000/reference でアクセスできるようになります。
なお、ドキュメンテーションを無効にする場合は、None を設定します。
app = FastAPI(docs_url=None, redoc_url=None)
この設定により、Swagger UIとReDocのドキュメンテーションは無効になり、URLからアクセスすることはできません。これは、本番環境でドキュメンテーションを非公開にする場合などに便利です。ただし、開発中はドキュメンテーションが有効であることが推奨されます。これにより、APIの開発とテストが容易になります。
FastAPIのOpenAPIを無効にする
FastAPIは、デフォルトでOpenAPIに基づいたAPIドキュメンテーションを生成します。しかし、特定の状況下では、このドキュメンテーションを無効にしたい場合があります。たとえば、本番環境でAPIの詳細を非公開にしたい場合などです。
FastAPIのOpenAPIドキュメンテーションを無効にするには、FastAPIのインスタンスを作成する際に、openapi_url パラメータを None に設定します。
以下に、OpenAPIドキュメンテーションを無効にする例を示します。
from fastapi import FastAPI
app = FastAPI(openapi_url=None)
この設定により、OpenAPIのドキュメンテーションは無効になり、URLからアクセスすることはできません。ただし、開発中はドキュメンテーションが有効であることが推奨されます。これにより、APIの開発とテストが容易になります。
なお、Swagger UIとReDocのドキュメンテーションも同様に無効にすることができます。その場合は、docs_url と redoc_url パラメータをそれぞれ None に設定します。
app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
この設定により、Swagger UI、ReDoc、およびOpenAPIのすべてのドキュメンテーションが無効になります。これは、本番環境でAPIの詳細を非公開にする場合などに便利です。ただし、開発中はドキュメンテーションが有効であることが推奨されます。これにより、APIの開発とテストが容易になります。
終わりに
FastAPIは、高速で強力なWebフレームワークであり、その自動化されたOpenAPIドキュメンテーション機能は、APIの開発と利用を大いに助けます。しかし、特定の状況下では、これらのドキュメンテーションを無効にしたい場合があります。本記事では、FastAPIのOpenAPIドキュメンテーションを無効にする方法、およびSwagger UIとReDocのURLをカスタマイズする方法について説明しました。
これらの設定を適切に使用することで、開発者はAPIのドキュメンテーションを効率的に管理し、APIの利用者はAPIの使用方法を容易に理解することができます。これは、APIの開発と利用の両方を効率化し、生産性を向上させます。
FastAPIは、その柔軟性と強力な機能により、APIの開発を簡単で楽しいものにします。本記事が、あなたのFastAPIによるAPI開発の旅をさらに進める一助となれば幸いです。それでは、Happy coding! 🚀