✨

[memo] Fast APIで個人的によく使うSwagger docsの書き方

2024/10/05に公開

Python

最近利用することが多いのでメモをしておきます。

FastAPIでは標準でOpenAPIのAPIドキュメントを生成する機能が用意されています。

Swagger : docs
ReDoc : redoc

これらのドキュメントは、コードの内容に応じて自動的に生成され、インタラクティブに使用することができます。Swaggerは特に、APIのエンドポイントを実際にテストするためのUIを提供しています。

サンプル

from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
from middleware import Middleware
from models.user_info import UserInfo
from starlette import status
from error_response import (
    UnexpectedErrorBody,
    ValidationErrorBody,
)
from pydantic import BaseModel, Field

router = APIRouter()
middleware = Middleware()


class MessageRequestBody(BaseModel):
    question: str = Field(
        default="こんにちは。",
        description="質問内容",
    )


class MessageJsonResponse(BaseModel):
    answer: str = Field(
        ...,
        description="回答",
    )


@router.post(
    "/v1/messages",
    tags=["message"],
    response_model=MessageJsonResponse,
    responses={
        status.HTTP_422_UNPROCESSABLE_ENTITY: {
            "model": ValidationErrorBody,
            "description": "Validation Error",
        },
        status.HTTP_500_INTERNAL_SERVER_ERROR: {
            "model": UnexpectedErrorBody,
            "description": "Internal Server Error",
        },
    },
)
async def messages(
    request: Request,
    request_body: MessageRequestBody,
    user_info: UserInfo = Depends(middleware.exec),
) -> JSONResponse:
    """
    このエンドポイントはテストメッセージを生成します。

    - **question**: 質問の内容。
    """

    return MessageJsonResponse(answer="どうも")

こんな感じでDocsが生成されます。

説明

response_model

response_model=MessageJsonResponse,

APIのレスポンスとして返されるデータの形式を指定します。

responses

responses={
    status.HTTP_422_UNPROCESSABLE_ENTITY: {
        "model": ValidationErrorBody,
        "description": "Validation Error",
    },
    status.HTTP_500_INTERNAL_SERVER_ERROR: {
        "model": UnexpectedErrorBody,
        "description": "Internal Server Error",
    },
},

エンドポイントが返す可能性のあるHTTPステータスコードとそのレスポンスのモデルを指定します。

コメントブロック

    """
    このエンドポイントはテストメッセージを生成します。

    - **question**: 質問の内容。
    """

docs内にコメントを残せます。

最後に

ごく一部の書き方ですが、このように書いていけばdocsがいい感じになります。

サンプル

説明

tags

response_model

responses

コメントブロック

最後に

Discussion