Я не знаю точных возможностей FastAPI по генерации документации, но предположу основные ограничения, универсальные для такого подхода:
1. По описанию правил и ограничений в данных вы ограничены той коробочной валидацией, которую дает фреймворк. Если что-то валидируете уже своими силами, в документацию это не попадет. Часто для этого фреймворки оставляют вмешаться в процесс генерации и что-то там поправить, но это еще один слой программирования, поддержания актуальности и новые места для ошибок.
2. Вы доверяете генератору в своей фреймворке. Где-то они работают относительно надежно, где-то нет, т.е. подход сам по себе ненадежный, если смотреть глобально.
3. Вы используете только этот фреймворк и язык. Захочется поменять язык или добавить в АПИ сервис на другом языке, появится много ручного труда, собирание документации из разных источников, а описанные выше проблемы умножатся на 2.
Пишу на FastAPI. Документация создаётся автоматически при описании эндпойнтов в коде. ЧЯДНТ?))
Я не знаю точных возможностей FastAPI по генерации документации, но предположу основные ограничения, универсальные для такого подхода:
1. По описанию правил и ограничений в данных вы ограничены той коробочной валидацией, которую дает фреймворк. Если что-то валидируете уже своими силами, в документацию это не попадет. Часто для этого фреймворки оставляют вмешаться в процесс генерации и что-то там поправить, но это еще один слой программирования, поддержания актуальности и новые места для ошибок.
2. Вы доверяете генератору в своей фреймворке. Где-то они работают относительно надежно, где-то нет, т.е. подход сам по себе ненадежный, если смотреть глобально.
3. Вы используете только этот фреймворк и язык. Захочется поменять язык или добавить в АПИ сервис на другом языке, появится много ручного труда, собирание документации из разных источников, а описанные выше проблемы умножатся на 2.
Александр, ВВДТ)) FastAPI — отличный фреймворк. Если он вас устраивает, то ничего больше не нужно)