Атрибут openapi_schema

Атрибут openapi_schema применяется к экземпляру класса FastAPI и возвращает словарь, в котором лежит готовая OpenAPI-схема приложения. Схема строится на основе всех зарегистрированных маршрутов, моделей Pydantic и метаданных приложения: заголовка title, версии version, описания description и других параметров. Изначально атрибут равен None и заполняется словарём при первом обращении к эндпоинту /openapi.json или при явном вызове метода openapi. Атрибут доступен только для чтения: менять его напрямую не следует, так как FastAPI сам управляет его содержимым.

Схема представляет собой обычный словарь Python, который можно передать в JSON-сериализатор, сохранить в файл или проанализировать программно.

Синтаксис

app.openapi_schema

Атрибут возвращает словарь dict или значение None, если схема ещё не построена.

Пример

Давайте создадим приложение с одним маршрутом и посмотрим на содержимое атрибута openapi_schema до и после обращения к схеме:

from fastapi import FastAPI

app = FastAPI(title='My API', version='1.0.0')

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

print(app.openapi_schema)
schema = app.openapi()
print(app.openapi_schema)

Результат выполнения кода:

None
{'openapi': '3.1.0', 'info': {'title': 'My API', 'version': '1.0.0'}, 'paths': {'/': {'get': {...}}}}

Первый вывод показывает None, так как схема ещё не строилась. После вызова метода openapi атрибут заполняется словарём, содержащим ключи openapi, info и paths.

Пример

Давайте сохраним построенную схему в JSON-файл:

<+python+> import json from fastapi import FastAPI app = FastAPI(title='My API', version='1.0.0') @app.get('/user/{name}') def user(name: str): return {'name': name} schema = app.openapi() with open('openapi.json', 'w') as f: json.dump(schema, f, indent=2) <-python+>

После выполнения кода в файле openapi.json будет лежать полная OpenAPI-схема приложения.

Пример

Давайте программно посмотрим на список путей, попавших в схему:

<+python+> from fastapi import FastAPI app = FastAPI() @app.get('/') def index(): return {'text': 'hello'} @app.get('/user/{name}') def user(name: str): return {'name': name} schema = app.openapi() res = list(schema['paths'].keys()) print(res) <-python+>

Результат выполнения кода:

['/', '/user/{name}']

Ключи словаря paths совпадают с URL-шаблонами зарегистрированных маршрутов.

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

метод openapi,
который строит и возвращает OpenAPI-схему
атрибут openapi_url,
который задаёт адрес эндпоинта со схемой
атрибут title,
который задаёт название приложения в схеме
атрибут version,
который задаёт версию приложения в схеме