API仕様書は、開発者がAPIを効率よく使用できるようにするための重要なドキュメントです。SwaggerとOpenAPIを使用して、API仕様書を簡単かつ正確に作成する方法を説明します。本記事では、具体的なコード例、その詳細な解説、および応用例を含めています。
目次
SwaggerとOpenAPIの概要
SwaggerとOpenAPIは、RESTful APIの仕様を定義、ビルド、ドキュメント化、消費するためのフレームワークです。Swaggerは元々独自の仕様でしたが、OpenAPI Initiativeによって標準化され、現在はOpenAPI Specification（OAS）として広く知られています。
必要なツール
本チュートリアルで必要なツールは以下のとおりです。
- Python 3.x
- Swagger UI
- Swagger Editor
基本的なAPI仕様書の作成
最初に基本的なAPI仕様書を作成してみましょう。ここでは、PythonのFastAPIを用いた例を出します。
FastAPIを使った基本的なAPI仕様書の作成
FastAPIは、Pythonで書かれたモダンな高速なWebフレームワークで、OpenAPIとSwagger UIが組み込まれています。
# FastAPIのインストール
!pip install fastapi
!pip install uvicorn
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, World"}
# コマンドラインで以下のコマンドを実行
# uvicorn main:app --reload
これを実行すると、`http://127.0.0.1:8000/docs`でSwagger UIによるAPI仕様書が自動的に生成されます。
応用例
認証を持つAPI仕様書
FastAPIを用いて、JWT認証を含むAPI仕様書を作成する例です。
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import OAuth2PasswordBearer
app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
@app.get("/items/")
async def read_item(token: str = Depends(oauth2_scheme)):
if token != "mytoken":
raise HTTPException(status_code=401)
return {"token": token}
複数のリソースを持つAPI仕様書
複数のエンドポイントとリソースを持つAPIを設計する例です。
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/")
def read_users():
return {"message": "List of users"}
@app.get("/users/{user_id}")
def read_user(user_id: int):
return {"message": f"User {user_id}"}
@app.get("/articles/")
def read_articles():
return {"message": "List of articles"}
まとめ
SwaggerとOpenAPIを使用することで、API仕様書の作成が効率的に行えます。特にPythonのFastAPIを用いると、コード内でAPIの仕様を簡単に定義でき、自動的にドキュメントを生成することが可能です。この知識を基に、より複雑なAPI設計にも応用してみてください。
コメント