Есть несколько способов или подходов:

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 сервисов.

Но писать руками файл спецификации удобно в том случае, когда создание сервиса на этапе планирования. Если сервис уже существует, то удобней пользоваться фреймворками и конструкторами.

Профит в том, что имея (или не имея) серверную реализацию REST API или файл спецификации OpenAPI (Swagger) вы можете:

- автоматически генерировать к ней документацию
- автоматически генерировать клиентский код к этому REST API для множества языков программирования
- проектировать Api с помощью спецификации, а реализацией на стороне клиента и на стороне сервиса могут заниматься не связанные друг с другом команды разработчиков

Например, вы можете воспользоваться расширением для Visual Studio 2017/2019 Unchase OpenAPI (Swagger) Connected Service для автоматической генерации C# или TypeScript кода для клиента (статья на medium.com), и C# кода контроллеров для сервера по файлу спецификации.
Фактически, после генерации кода контроллера их можно заполнить тем функционалом, который Вам нужен, а после вызывать методы контроллера из сгенерированного клиента.