Выберите версию API в поле Select a definition. Отобразится API выбранной версии:
Для версии публичного API в заголовке будет указано Public API version X.0, для внутреннего — Internal API version XX.0, где X — номер версии
После заголовка отображается список методов API, сгруппированных по типу сущности
Рядом с названием группы методов приведено общее описание
Для внутреннего API поддерживаются только две версии:
Версия текущего релиза.
Версия предыдущего релиза.
Чтобы выбрать конкретный метод:
Выберите группу методов и нажмите кнопку .
Выберите метод и нажмите кнопку . Раскроется подробная информация о методе:
Описание конкретного метода
Описание необходимых заголовков
Описание входных параметров с типами
Описание возможных вариантов результата
Общие принципы работы в 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.
Чтобы пройти общую аутентификацию, выполните следующие действия:
Нажмите кнопку Authorize или выберите метод и нажмите кнопку . Откроется окно аутентификации. Откроется окно доступных авторизаций.
Укажите данные вашей учетной записи в Case.one: Логин и Пароль через пробел.
Нажмите кнопку Authorize. Отобразится статус аутентификации.
Нажмите кнопку Close или в окне.
Если вы хотите выйти или изменить данные учетной записи, нажмите кнопку Logout.
Пример работы с методом
Работа с публичным API описана на примере выполнения метода GET /api/v2/events — получение списка событий.
Чтобы выполнить запрос:
Выберите группу методов, например, Events.
Выберите метод (например, GET /api/v2/events — получение списка событий) и нажмите кнопку . Раскроется структура метода.
Нажмите кнопку Try it out. Исходящие параметры метода станут доступны для редактирования.
Заполните исходящие параметры:
Укажите значения в полях параметров метода при наличии:
caseId — идентификатор дела для фильтрации событий по делу. Чтобы узнать идентификатор дела или другой сущности:
Откройте карточку дела (сущность)
В строке браузера найдите нужный идентификатор и скопируйте его
pageSize — максимальное количество сущностей на странице (15)
Укажите значения параметров запроса при наличии.
Нажмите кнопку Execute. Выполнятся отправка запроса и получение ответа — например, в результате будет возвращен список событий конкретного дела после выполнения запроса CaseMap.PublicApi.Pagination.Page[CaseMap.PublicApi.Events.Event].
Ознакомьтесь с результатами работы метода:
Блок запроса Curl (client URL), который содержит:
Наименование инстанса — instance_name.case.one
Наименование метода — api/v2/events
Параметры метода — CaseId=ff88b23e-2844-5634-54cf-b09200dffa55 и PageSize=15
Блок 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 — успешное выполнение метода
.
.
— позволяет скопировать наименование метода, отображается только при наведении
в окне.
