Расширение схемы OpenAPI для лучшей документации
Прочитав этот фрагмент, вы научитесь изменять сгенерированную схему OpenAPI и добавлять образцы кода в ReDoc конечную точку в вашем приложении FastAPI. В этом руководстве также рассматривается динамическое добавление образцов кода из текстовых файлов вместо определения кода внутри вашего сценария FastAPI.
Начиная с версии 2.0, ReDoc предоставляет отличную поддержку примеров кода через расширение поставщика. Все, что вам нужно сделать, это объявить новый элемент с именем x-codeSamples для каждого из имеющихся у вас маршрутов. x-codeSamples должен содержать список объектов образца кода, который может быть представлен следующим образом:
- язык
- метка
- источник
язык
Строка, представляющая язык примера кода. Это влияет на рендеринг и цвета ваших образцов кода. Значение должно быть одним из следующих:
- C
- C#
- C++
- CoffeeScript
- CSS
- Дротик
- DM
- Эликсир
- Go
- Groovy
- HTML
- Ява
- JavaScript
- Котлин
- Цель-C
- Perl
- PHP
- PowerShell
- Python
- Рубин
- Ржавчина
- Скала
- Оболочка
- Быстрый
- Машинопись
метка
Необязательная строка label для примеров кода. Этот ярлык будет отображаться в документации. Если метка отсутствует, по умолчанию будет использоваться lang.
источник
Исходный код для ваших примеров кода. Он представлен в виде одной строки. Обратите внимание, что синтаксис не проверяется. Вы обязаны убедиться, что код работает без ошибок.
Переходим к следующему разделу и приступаем к установке необходимых модулей.
Настраивать
Перед продолжением установки настоятельно рекомендуется создать новую виртуальную среду.
FastAPI
Активируйте его и выполните следующую команду, чтобы установить FastAPI:
pip install fastapi
Увикорн
Для обслуживания сервера FastAPI требуется сервер ASGI. Вы можете выбрать установку минимального количества зависимостей через:
pip install uvicorn
или стандартная установка, которая содержит дополнительные полезные пакеты, такие как поддержка WebSockets.
pip install uvicorn[standard]
Файл требований
Кроме того, вы можете установить все необходимые пакеты с помощью следующего файла требований:
click 7.1.2 dataclasses 0.8 fastapi 0.63.0 h11 0.12.0 httptools 0.1.1 pip 21.0.1 pkg-resources 0.0.0 pydantic 1.8.1 python-dotenv 0.15.0 PyYAML 5.4.1 setuptools 54.1.1 starlette 0.13.6 typing-extensions 3.7.4.3 uvicorn 0.13.4 uvloop 0.14.0 watchgod 0.7 websockets 8.1
Сохраните его в том же рабочем каталоге, что и requirements.txt, и запустите:
pip install -r requirements.txt
Настройте документацию с помощью логотипа
В этом разделе вы реализуете сценарий сервера FastAPI и расширяете базовую спецификацию OpenAPI. Начнем с тестирования индивидуализированной документации с логотипом. Создайте новый файл Python с именем myapp.py.
Импортировать
Добавьте следующие операторы импорта вверху файла.
from fastapi import FastAPI from fastapi.openapi.utils import get_openapi
Маршруты
Инициализируйте экземпляр FastAPI и добавьте к нему два новых маршрута.
app = FastAPI()
@app.get("/hello")
async def hello():
return [{"message": "hello"}]
@app.get("/world")
async def world():
return [{"message": "world"}]
Пользовательский OpenAPI
Затем объявите новую функцию, которая переопределит схему OpenAPI по умолчанию. Он кэширует сгенерированную схему и повторно использует ее для следующего запроса.
Кстати, вы должны убедиться, что
app.openapi = custom_openapi
вызывается после того, как вы указали все маршруты, чтобы предотвратить ошибку с отсутствующим ключом при изменении схемы.
Запуск сервера
Сохраните файл Python и выполните следующую команду в своем терминале:
uvicorn myapp:app
Откройте браузер и перейдите по следующему URL-адресу:
http://localhost:8000/redoc
Вы должны увидеть следующий пользовательский интерфейс:
Настройте документацию с помощью примеров кода
Вы должны заметить, что добавить логотип так же просто, как изменить содержимое схемы:
openapi_schema["info"]["x-logo"] = { "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" }
Добавление одного образца кода
Чтобы добавить образец кода в конечную точку hello, вы должны изменить схему следующим образом:
openapi_schema["paths"]["/hello"]["get"]["x-codeSamples"] = [{
'lang': 'JavaScript',
'source': 'console.log("hello");',
'label': 'Plain JS'
}]
Важно указать перед маршрутом символ / и указать правильный метод HTTP (получение, публикация и т. Д.). Если вы столкнулись с KeyError при запуске сервера, дважды проверьте маршруты и методы, используемые в вашем скрипте.
Добавление нескольких образцов кода
Допустим, вы хотели поддержать образцы кода для нескольких разных языков программирования. Просто добавьте дополнительные элементы в список следующим образом:
openapi_schema["paths"]["/hello"]["get"]["x-codeSamples"] = [
{
'lang': 'JavaScript',
'source': 'console.log("hello");',
'label': 'Plain JS'
},
{
'lang': 'JavaScript',
'source': 'console.log("hello node");',
'label': 'NodeJS'
},
]
Повторно запустите свой сервер FastAPI, и вы должны увидеть следующие образцы кода.
Динамическая загрузка образцов кода из текстовых файлов
Процесс добавления образцов кода непосредственно в файл Python довольно утомителен, особенно если вы намереваетесь поддерживать разные языки программирования для нескольких маршрутов.
Создание папок
Давайте сделаем еще один шаг и реализуем новую функцию, которая загружает весь файл и динамически добавляет его в схему. Создайте новую папку с именем docs. Внутри папки добавьте еще две папки следующим образом:
- Обычный JS
- NodeJS
Создание текстовых файлов
Обратите внимание, что имя папки будет использоваться в качестве метки, которая будет отображаться в документации. Внутри каждой папки создайте два новых текстовых файла:
- привет-get.js
- world-get.js
Соглашение об именах основано на следующем фрагменте кода, в котором имена маршрутов и HTTP-метода разделены дефисом. Если у вас есть следующий маршрут GET:
v1/hello
вы должны назвать файл следующим образом:
v1-hello-get.js
Расширение файла не имеет значения, и вы можете использовать все, что захотите (например, txt). Рекомендуется использовать правильное расширение файла, так как вы можете сразу проверить его, чтобы убедиться, что код работает правильно.
Когда вы закончите, давайте реализуем оставшийся код внутри вашего файла Python.
Импортировать
Добавьте следующий импорт и сопоставление dict
...
import os
lable_lang_mapping = {"Plain JS": "JavaScript", "NodeJS": "JavaScript"}
...
Реализация пользовательской функции
Создайте новую функцию с именем add_examples, которая выполняет поиск в папке docs и загружает содержимое текстовых файлов в качестве примеров кода в вашу схему OpenAPI.
Затем измените следующую строку:
app.openapi_schema = openapi_schema
to
app.openapi_schema = add_examples(openapi_schema, 'docs')
Документация
Сохраните файл и перезапустите сервер. Вы должны увидеть следующий пользовательский интерфейс
Вы можете найти полный код по следующей сути.
Вывод
Подведем итоги тому, что вы узнали сегодня.
Это руководство началось с краткого объяснения поддержки примеров кода через расширение поставщика для ReDoc.
Затем он описывает процесс установки через прямую установку pip или файл требований.
После этого он сосредоточился на настройке схемы OpenAPI для включения пользовательского логотипа в документацию. Впоследствии он объяснил, как добавлять образцы кода в документацию непосредственно внутри файла Python.
И последнее, но не менее важное: в нем рассказывается, как динамически добавлять образцы кода из текстовых файлов.
Спасибо, что прочитали эту статью. Надеюсь, вы вернетесь, чтобы прочитать следующую статью!
