Обычно API описываю с помощью OpenAPI (Swagger) спецификации. Это позволяет формально задать все эндпоинты, методы, параметры, схемы запросов и ответов, а также коды ошибок.

В Go часто использую инструменты, которые генерируют документацию из кода или наоборот — генерируют серверный код из OpenAPI спецификации.

Пример описания ручки в OpenAPI:

paths:
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден

Такой подход помогает поддерживать документацию в актуальном состоянии и облегчает интеграцию с клиентами.

Как обычно описываешь API? Например, у тебя есть веб-сервис с ручками.