Параметр include_in_schema

Параметр include_in_schema применяется к методам маршрутизации FastAPI, таким как get, post, put и другим. Он принимает булево значение и определяет, будет ли маршрут включён в автоматически генерируемую OpenAPI-схему и, соответственно, отображаться в интерактивной документации Swagger UI и ReDoc. По умолчанию параметр равен True, то есть все маршруты попадают в схему. Если установить False, маршрут продолжит работать, но станет невидимым для документации.

Синтаксис

@app.get(path, include_in_schema=False)

Пример

Давайте создадим два маршрута: один публичный, который отобразится в документации, и один служебный, скрытый от посторонних глаз:

from fastapi import FastAPI

app = FastAPI()

@app.get('/')
def index():
	return {'text': 'hello'}

@app.get('/secret', include_in_schema=False)
def secret():
	return {'text': 'hidden'}

После запуска сервера и открытия адреса /docs в списке маршрутов будет виден только /. Маршрут /secret при этом продолжит отвечать на запросы:

{"text": "hidden"}

Пример

Параметр include_in_schema можно комбинировать с другими параметрами, например с tags и summary. Давайте скроем от документации целую группу служебных маршрутов:

from fastapi import FastAPI

app = FastAPI()

@app.get('/user', tags=['users'])
def get_user():
	return {'name': 'user'}

@app.get('/health', include_in_schema=False)
def health():
	return {'status': 'ok'}

@app.get('/metrics', include_in_schema=False)
def metrics():
	return {'value': 1}

В Swagger UI появятся только маршруты с include_in_schema=True. Служебные маршруты /health и /metrics останутся доступными по прямым запросам, но не будут показаны в интерактивной документации.

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

метод get,
который вешает обработчик на GET-запрос
метод api_route,
который вешает обработчик на произвольный HTTP-метод
атрибут openapi_schema,
который хранит сгенерированную OpenAPI-схему
метод openapi,
который возвращает OpenAPI-схему приложения