Есть несколько способов или подходов:
1) Да, есть библиотеки (фреймворки), которые генерируют файл спецификации по коду, а уже по этому файлу - документацию, например,
Swashbuckle,
NSwag и пр. В этом случае разработчику достаточно использовать специальные средства фреймворка (такие как аннотации) и обычные комментарии к коду, по которым и будет сгенерирован файл спецификации и уже после документация по нему. То есть этот файл - не посредник, а необходимый "артефакт", без него вы все равно не сгенерируете документацию.
Кроме того, по этому сгенерированному файлу уже можно будет автоматически генерировать код клиента на различных языках программирования. Например, для C# и TypeScript, используя
Unchase OpenAPI (Swagger) Connected Service в IDE Visual Studio 2017/2019, можно легко это сделать (
статья на medium.com).
2) Другой подход подразумевает сначала создание файла спецификации для REST API (в yaml или json), а после генерации из него и кода клиентов, и кода контроллеров сервиса (например, и то, и другое можно сделать с помощью
Unchase OpenAPI (Swagger) Connected Service), а также документации. При этом сам файл не обязательно писать руками, есть конструкторы для OpenAPI сервисов.
Но писать руками файл спецификации удобно в том случае, когда создание сервиса на этапе планирования. Если сервис уже существует, то удобней пользоваться фреймворками и конструкторами.
Простой
Простой
