Перейти на сайт Case.one

Общие принципы работы в Swagger

Методы в Swagger могут быть двух типов:

  • Общедоступные — не требуют авторизации.
  • Закрытые — для выполнения запроса требуется аутентификация (в конце строки метода отображается кнопка .

Заголовки (headers) в REST API:

  • Определяют:
    • Формат передаваемых данных.
    • Спецификацию и версию протокола обмена.
    • Другую информацию, необходимую для корректной обработки запроса.
  • Не отображаются в пути запроса.

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

Для удобства восприятия в Swagger методы подсвечены цветами:

  • POST и PATCH — отвечают за создание и изменение сущностей, выделены зелеными цветами.
  • PUT — отвечают за обновление сущности, выделены оранжевым цветом.
  • GET — отвечают за получение сущности или списка сущности, выделены светло-синим цветом.
  • DELETE — отвечают за удаление сущности, выделены красным цветом.

Особенности параметров метода:

  • Основные типы параметров:
    • String — Строка
    • Integer — Целое число
    • Number — Число
    • {} — Системный объект
  • Обязательные параметры всегда отмечены символом *.
  • Параметры могут:
    • Быть различных подтипов, например:
      • string($date-time) — строка в формате Дата и время
      • string($uuid) — строка, содержащая идентификатор
    • Содержать ограничения, например:
      • maxLength: 100 — ограничение на максимальную длину в 100 символов
      • minLength: 1 — ограничение на минимальное количество символов (1 символ)
    • Быть объединены в массивы — Array:
      • Отдавать значение null при отсутствии данных (значение элемента может быть пустым) — nullable: true
      • Быть нередактируемыми (только для чтения) — readOnly: true

Структура метода:

  • Строка метода:
    • Наименование метода
    • Краткое описание
    • Кнопка раскрытия параметров метода
    • Кнопка , если для выполнения запроса требуется аутентификация
    • Кнопка  — позволяет скопировать наименование метода, отображается только при наведении
  • Описание метода.
  • Parameters — блок исходящих параметров и запросов метода, где отображаются:
    • Кнопка вызова метода Try it out — позволяет передать параметры
    • Параметры метода:
      • Исходящие параметры
      • Параметры исходящего запроса
    • Поле выбора/просмотра формата данных метода
    • Кнопки выбора режима просмотра параметров:
      • Example Value — пример
      • Schema — детальная схема параметров
    • Блок с параметрами
  • Responses — блок входящих параметров и запросов метода, где отображается перечень кодов ответа (Code) с детальным описанием (Description) и ссылками (Links) при наличии (если ссылок нет, отображается No links):
    • Код ответа, например, 200
    • Описание ответа
    • Поле выбора/просмотра формата данных метода
    • Сведения о передаче заголовка при наличии, например: Controls Accept header — настройки: принять заголовок
    • Кнопки выбора режима просмотра параметров:
      • Example Value — пример
      • Schema — детальная схема параметров
      • Блок с параметрами

Общая аутентификация в Swagger

В Swagger Case.one предусмотрено несколько вариантов аутентификации:

  • Общая.
  • С помощью методов группы Auth.

Чтобы пройти общую аутентификацию, выполните следующие действия:

  1. Нажмите кнопку Authorize или выберите метод и нажмите кнопку . Откроется окно аутентификации. Откроется окно доступных авторизаций.
  2. Укажите данные вашей учетной записи в Case.one: Логин и Пароль через пробел.
  3. Нажмите кнопку Authorize. Отобразится статус аутентификации.
  4. Нажмите кнопку Close или  в окне.

Если вы хотите выйти или изменить данные учетной записи, нажмите кнопку Logout.

Пример работы с методом

Работа с публичным API описана на примере выполнения метода GET /api/v2/events — получение списка событий.

Чтобы выполнить запрос:

  1. Выберите группу методов, например, Events.
  2. Выберите метод (например, GET /api/v2/events — получение списка событий) и нажмите кнопку . Раскроется структура метода.
  3. Нажмите кнопку Try it out. Исходящие параметры метода станут доступны для редактирования.
  4. Заполните исходящие параметры:
  5. Укажите значения в полях параметров метода при наличии:
    • caseId — идентификатор дела для фильтрации событий по делу. Чтобы узнать идентификатор дела или другой сущности:
      • Откройте карточку дела (сущность)
      • В строке браузера найдите нужный идентификатор и скопируйте его
    • pageSize — максимальное количество сущностей на странице (15)
  6. Укажите значения параметров запроса при наличии.
  7. Нажмите кнопку Execute. Выполнятся отправка запроса и получение ответа — например, в результате будет возвращен список событий конкретного дела после выполнения запроса CaseMap.PublicApi.Pagination.Page[CaseMap.PublicApi.Events.Event].
  8. Ознакомьтесь с результатами работы метода:
    • Блок запроса Curl (client URL), который содержит:
      • Наименование инстанса — instance_name.case.one
      • Наименование метода — api/v2/events
      • Параметры метода — CaseId=ff88b23e-2844-5634-54cf-b09200dffa55 и PageSize=15
      • Формат данных — application/json
        curl -X 'GET' \
          'https://instance_name.case.one/api/v2/events?CaseId=ff88b23e-2844-5634-54cf-b09200dffa55&PageSize=15' \
          -H 'accept: application/json'
    • Блок Request URL с URL-адресом запроса, который содержит:
      • Наименование инстанса — ://instance_name.case.one/
      • Наименование метода — api/v2/events
      • Параметры метода — CaseId=ff88b23e-2844-5634-54cf-b09200dffa55 и PageSize=15
        https:// instance_name.case.one/api/v2/events?CaseId=ff88b23e-2844-5634-54cf-b09200dffa55&PageSize=15
    • Блок Server response с ответом сервера:
      • Код ответа — например, 200 — успешное выполнение метода
      • Response body  — тело ответа
      • Response headers — заголовки ответа, например:
        Response headers
         api-deprecated-versions: 72.0
         api-supported-versions: 1.0,2.0,3.0,73.0
         cache-control: no-store,no-cache
         content-length: 1196
         content-type: application/json; charset=utf-8
         date: Sun,02 Jun 2024 13:28:38 GMT
         pragma: no-cache
         server: Microsoft-IIS/10.0
         strict-transport-security: max-age=2592000
         x-powered-by: ASP.NET

В результате выполнения метода GET /api/v2/events будет получен список событий, отфильтрованный по делу, со следующими сведениями:

  • Items — список событий.
  • CaseMap.PublicApi.Events.Event — информация по каждому событию с параметрами:
    • Наименование — Name
    • Описание — Description
    • Дата начала — StartDate
    • Дата окончания — EndDate
    • Признак продолжительности события весь день — AllDay
    • Базовый класс сущности — Type:
      • Id (строка($uuid), обязательный параметр) — идентификатор сущности
      • CreationDate (строка($date-time), необязательный параметр) — дата создания в формате UTC
      • LastChangeDate (строка($date-time), необязательный параметр) — дата последнего изменения в формате UTC
      • Url (строка, необязательный параметр) — URL этой сущности
    • Базовый класс сущности — Case:
      • Id (строка($uuid), обязательный параметр) — идентификатор сущности
      • CreationDate (строка($date-time), необязательный параметр) — дата создания в формате UTC
      • LastChangeDate (строка($date-time), необязательный параметр) — дата последнего изменения в формате UTC
      • Url (строка, необязательный параметр) — URL этой сущности
    • Участники — Attendees:
      • Id (строка($uuid), необязательный параметр) — идентификатор объекта
      • CreationDate (строка($date-time), необязательный параметр) — дата создания в формате UTC (только для чтения)
      • LastChangeDate (строка($date-time), необязательный параметр) — дата последнего изменения в формате UTC (только для чтения)
      • Url (строка, необязательный параметр) — URL этой сущности (только для чтения)
      • EntityId (строка($uuid), необязательный параметр) — идентификатор сущности
      • Type (строка, обязательный параметр) — тип = ['Email', 'Participant', 'User'] (Адрес электронной почты, Участник, Пользователь)
      • Email (строка, необязательный параметр) — адрес электронной почты
    • Идентификатор сущности — Id
    • Дата создания в формате UTC — CreationDate
    • Дата последнего изменения в формате UTC — LastChangeDate
    • URL этой сущности — Url