Параметр responses

Параметр responses применяется к декораторам маршрутов FastAPI, таким как get, post, put и другим. Он позволяет описать дополнительные HTTP-ответы, которые маршрут может возвращать помимо основного. Значением параметра является словарь, где ключ - это код статуса, а значение - словарь с описанием ответа: description, model, content и другими полями.

Синтаксис

@app.get(path, responses={status_code: {...}})

Пример

Давайте опишем дополнительный ответ со статусом 404:

from fastapi import FastAPI

app = FastAPI()

@app.get('/user', responses={404: {'description': 'User not found'}})
def get_user():
	return {'name': 'abcde'}

Теперь в документации OpenAPI у маршрута /user появится описание ответа 404 с текстом 'User not found'.

Пример

Давайте укажем модель ответа для дополнительного статуса:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class ErrorModel(BaseModel):
	detail: str

@app.get('/article', responses={400: {'model': ErrorModel, 'description': 'Invalid request'}})
def get_article():
	return {'title': 'hello'}

Модель ErrorModel будет использована для схемы ответа со статусом 400.

Пример

Давайте добавим пример тела ответа через ключ content:

from fastapi import FastAPI

app = FastAPI()

@app.get(
	'/items',
	responses={
		500: {
			'description': 'Internal error',
			'content': {
				'application/json': {
					'example': {'detail': 'server error'}
				}
			}
		}
	}
)
def get_items():
	return ['a', 'b', 'c', 'd', 'e']

В документации для статуса 500 появится пример тела ответа в формате JSON.

Смотрите также

параметр response_model,
который задаёт основную модель ответа маршрута
параметр status_code,
который задаёт основной код статуса ответа
метод get,
который регистрирует обработчик GET-запроса
метод api_route,
который вешает обработчик на произвольный HTTP-метод