Разница между подходами написания документации в Swagger на основании кода и отдельно от кода заключается в том, что первый подход проще, а второй позволяет создавать более подробные и понятные описания. 3

Подход на основании кода предполагает, что инструмент «читает» код API и на его основе генерирует документацию. 3 От разработчика не требуется знать спецификацию и писать что-то помимо самого кода. 3 Такой способ считают простым, но его рекомендуют применять только тогда, когда документация нужна срочно. 3 При этом подходе код проекта становится не очень читабельным из-за обилия аннотаций и описаний в нём. 1

Подход отдельно от кода предполагает использование спецификации Swagger (OpenAPI). 3 Этот способ сложнее, потому что необходимо знать язык формальных правил. 3 На нём нужно описать сущности кода, чтобы инструмент понял написанное и сгенерировал документ. 3 Такой подход считают более правильным, потому что такая документация более понятна и человекочитаема. 3 Писать необходимо с помощью форматов JSON или YAML либо в специальном редакторе Swagger Editor. 3

Таким образом, первый подход подходит для быстрого создания документации, а второй — для более подробного и понятного описания. 3