Комментарии 4
С недавних пор Pydantic умеет брать описания полей из так называемых attribute docstrings:
class RequestPoint(NavigationApiBaseModel):
"""Координаты точки маршрута."""
lat: float
"""Градусы долготы."""
lon: float
"""Градусы широты."""
Чтобы использовать нужно включить соответствующий параметр в конфиге модели.
То есть у вас описание OpenAPI для сервиса пишется тестировщиками, а не генерируется на основе исходного кода сервиса? А вам не кажется, что это с концепцией единого источника знаний не согласуется? Подробности работы с Pydentic это конечно любопытно, но такой подход гарантирует, что описание OpenAPI периодически не будет соответствовать поведению сервиса и его моделям. Вы постоянно будете догонять в документации изменившееся фактическое положение дел. Может не стоит телегу впереди лошади запрягать? И пытаться решать инженерными средствами задачу, которая требует управленческого решения?
OpenAPI описание не пишется, оно генерируется из модели. Модели правят не обязательно тестировщики, чаще всего их правит разработка при реализации фичи. Иначе они просто не смогут влить правки в код, т.к. тесты не пройдут и влитие будет заблокировано. А часть сервисов, которые написаны на Python, сами эти модели используют и тут без исправления моделей вообще не обойтись. Если изменения более серьезные, например, добавляется новый эндпоинт, у разработки заводится задача на изменение документации и вместе с техническим писателем готовится текст описания.
Генерация документации из моделей с помощью Pydantic