Как выглядит твой артефакт при описании REST-контракта?

Артефакт для описания REST-контракта обычно представляет собой документ или набор файлов, в которых формализовано описание API — его эндпоинтов, методов, параметров, форматов запросов и ответов, кодов ошибок и т.д.

Чаще всего используется спецификация OpenAPI (ранее Swagger), которая позволяет структурировано описать REST API в формате YAML или JSON. Такой документ служит основой для генерации документации, клиентских SDK и тестов.

Пример структуры OpenAPI:

openapi: 3.0.0
info:
  title: Пример API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Получить список пользователей
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

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