Если честно, я не очень понял второй пункт. Если речь о странице с HTML версией, то тот факт, что она показывается говорит только о корректном синтаксисе OpenAPI, но ничего не говорит о соотвествии документа задумке или реализации. В итоге, хоть даже и через гуи (редко приятнее исходника) нужно все равно вычитывать и проверять документ досканально. А потом с ним нужно еще и работать дальше. Т.е. в итоге вся реальная умственная работа все равно происходит с неудобным OpenAPI, даже если использовать AI как переводчик с человеческого.
Также не ясно, что тут являтеся источником истины. Если уже есть запросы, значит вы сначала реализуете, потом проектируете. Если есть какие-то наброски на псевдокоде, которые AI должен перевести в Openapi, то как вы по ним общаетесь, там вообще стандарта нет. Чаще всего и появляются json файлы с псевдокодом в комментариях. И даже если AI будет точно переводить это в openapi, то между собой участникам придется договариваться и придумывать свой внутренний стандарт.
А насчет обучения, так OpenAPI в среднем никто не знает, т.к. возиться с ним в массе люди не хотят. Работать нерегулярно с интутивным языком всегда будет проще. А тот, кто по обязанностям рабоатет с Openapi регулярно, выучит JSight за день и еще прилично места в голове освободит.
"Плохой и длинный синтексис" — это не проблема в вакууме. Это причина возникновения других проблем и мы старались решить именно их, а не просто дать способ записать то же самое покороче.
Я не знаю точных возможностей FastAPI по генерации документации, но предположу основные ограничения, универсальные для такого подхода:
1. По описанию правил и ограничений в данных вы ограничены той коробочной валидацией, которую дает фреймворк. Если что-то валидируете уже своими силами, в документацию это не попадет. Часто для этого фреймворки оставляют вмешаться в процесс генерации и что-то там поправить, но это еще один слой программирования, поддержания актуальности и новые места для ошибок.
2. Вы доверяете генератору в своей фреймворке. Где-то они работают относительно надежно, где-то нет, т.е. подход сам по себе ненадежный, если смотреть глобально.
3. Вы используете только этот фреймворк и язык. Захочется поменять язык или добавить в АПИ сервис на другом языке, появится много ручного труда, собирание документации из разных источников, а описанные выше проблемы умножатся на 2.
AI это, безусловно, очень современно. Но здесь вопрос в уровне доверия. Если рассматривать документацию как спецификацию, т.е. как контракт, то он должен быть точным. Использование кода бэкенда как исходника документации не гарантирует точности даже при использовании программных средств (во многих фреймворках есть такие фичи). С использованием AI проблем только прибавляется:
1. Как AI поймет реальные правила и ограничения данных из описания одного запроса? Предложенные готовые синтаксисы умеют описывать штучные запросы, но не схему данных.
2. Даже если сформулировать (что мы и сделали) или собрать из разных спецификаций синтаксис описания схемы и решить п.1, то как можно без редактуры использовать результат AI? Боюсь, что редактировать сочиненный ИИ OpenAPI еще больнее, чем писать его с нуля.
3. Как эту всю схему интегрировать в реальный рабочий процесс? Вот тут действительно возникнет очень специфичная новая область ответственности, которую нужно будет не то что поддерживать, а даже обслуживать.
Предложенная схема, конечно, может работать, но не ясно какую задачу она помогает решить.
Если честно, я не очень понял второй пункт. Если речь о странице с HTML версией, то тот факт, что она показывается говорит только о корректном синтаксисе OpenAPI, но ничего не говорит о соотвествии документа задумке или реализации. В итоге, хоть даже и через гуи (редко приятнее исходника) нужно все равно вычитывать и проверять документ досканально. А потом с ним нужно еще и работать дальше. Т.е. в итоге вся реальная умственная работа все равно происходит с неудобным OpenAPI, даже если использовать AI как переводчик с человеческого.
Также не ясно, что тут являтеся источником истины. Если уже есть запросы, значит вы сначала реализуете, потом проектируете. Если есть какие-то наброски на псевдокоде, которые AI должен перевести в Openapi, то как вы по ним общаетесь, там вообще стандарта нет. Чаще всего и появляются json файлы с псевдокодом в комментариях. И даже если AI будет точно переводить это в openapi, то между собой участникам придется договариваться и придумывать свой внутренний стандарт.
А насчет обучения, так OpenAPI в среднем никто не знает, т.к. возиться с ним в массе люди не хотят. Работать нерегулярно с интутивным языком всегда будет проще. А тот, кто по обязанностям рабоатет с Openapi регулярно, выучит JSight за день и еще прилично места в голове освободит.
"Плохой и длинный синтексис" — это не проблема в вакууме. Это причина возникновения других проблем и мы старались решить именно их, а не просто дать способ записать то же самое покороче.
Я не знаю точных возможностей FastAPI по генерации документации, но предположу основные ограничения, универсальные для такого подхода:
1. По описанию правил и ограничений в данных вы ограничены той коробочной валидацией, которую дает фреймворк. Если что-то валидируете уже своими силами, в документацию это не попадет. Часто для этого фреймворки оставляют вмешаться в процесс генерации и что-то там поправить, но это еще один слой программирования, поддержания актуальности и новые места для ошибок.
2. Вы доверяете генератору в своей фреймворке. Где-то они работают относительно надежно, где-то нет, т.е. подход сам по себе ненадежный, если смотреть глобально.
3. Вы используете только этот фреймворк и язык. Захочется поменять язык или добавить в АПИ сервис на другом языке, появится много ручного труда, собирание документации из разных источников, а описанные выше проблемы умножатся на 2.
.
AI это, безусловно, очень современно. Но здесь вопрос в уровне доверия. Если рассматривать документацию как спецификацию, т.е. как контракт, то он должен быть точным. Использование кода бэкенда как исходника документации не гарантирует точности даже при использовании программных средств (во многих фреймворках есть такие фичи). С использованием AI проблем только прибавляется:
1. Как AI поймет реальные правила и ограничения данных из описания одного запроса? Предложенные готовые синтаксисы умеют описывать штучные запросы, но не схему данных.
2. Даже если сформулировать (что мы и сделали) или собрать из разных спецификаций синтаксис описания схемы и решить п.1, то как можно без редактуры использовать результат AI? Боюсь, что редактировать сочиненный ИИ OpenAPI еще больнее, чем писать его с нуля.
3. Как эту всю схему интегрировать в реальный рабочий процесс? Вот тут действительно возникнет очень специфичная новая область ответственности, которую нужно будет не то что поддерживать, а даже обслуживать.
Предложенная схема, конечно, может работать, но не ясно какую задачу она помогает решить.