Насчет редактирования openapi, по следам предыдущего поста

Многие в комментах писали, что лучше генерировать спеку из кода, это быстрее и проще.

Возможно, в некоторых языках - это просто, но вот в Go или PHP, например, код сильно засирается аннотациями, посмотрите на пример: https://github.com/swaggo/swag/blob/master/example/celler/controller/examples.go

Т.е. мало того, что код засирается, так еще и надо знать, как правильно срать :), т.е. по сути помимо знания об openapi надо еще знать этот псевдоязык и к каким элементам кода его применять.

Ну и, конечно же, самое главное, легко забыть поменять аннотацию, поменяв код. Не будет гарантии, что код и дока соответствуют друг другу.

В общем, большой разницы тут нет, что руками править openapi доку, что так.

Только если фреймворк какого-то язывка прям всё сам делает и выдаёт готовенький блестящий openapi. Я слышал, что в Java как-то с этим получше, но тоже сомневаюсь, что идеально

Ну и главное: подход API design first позволяет сначала согласовать апи (с другой командой, с архитектором, с фронтендерами, с другой компанией, с которой вы интегрируетесь), а потом только пилить сам код.