OpenAPI в curl: команды запросов для терминала

Как получить готовые команды curl для каждой операции OpenAPI: адрес и токен в переменных окружения, параметры, заголовки и тела запросов из примеров.

curl есть почти на любом компьютере и сервере, поэтому команды curl — самый простой способ показать, как вызвать API: их вставляют в инструкции, тикеты и чаты. Помощник SA составит их по спецификации OpenAPI для всех операций сразу.

Как получить команды

Откройте спецификацию в редакторе OpenAPI (OpenAPI 3.x или Swagger 2.0).
Выберите Файл → Преобразовать в → curl — команды (.sh), скачать. Скачается скрипт <название>.sh.
Задайте переменные окружения и копируйте в терминал нужные команды.

Что внутри файла

В начале — переменные: адрес сервера из servers и секреты для авторизации. Их можно задать заранее (export TOKEN=…) или поправить в файле:

#!/usr/bin/env bash
# Заказы 1.0.0 — запросы curl по спецификации OpenAPI.
# Задайте переменные окружения (или поправьте значения ниже) и запускайте команды по одной.

BASE_URL="${BASE_URL:-https://api.shop.ru/v1}"
TOKEN="${TOKEN:-}"

Дальше — команда на каждую операцию, сгруппированные по тегам. Над командой — название операции, метод с путём и перечень необязательных параметров:

# ===== Заказы =====

# Список заказов
# GET /orders
# Необязательные параметры: status
curl "$BASE_URL/orders" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN"

# Создать заказ
# POST /orders
curl -X POST "$BASE_URL/orders" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "customer": "Иван Петров",
  "total": 1500
}'

Как строятся команды

Метод: для GET без тела -X не пишется, для HEAD — --head, для остальных — -X МЕТОД.
Параметры пути и обязательные параметры запроса подставлены значениями из примеров и закодированы для URL. Необязательные перечислены в комментарии: допишите те, что нужны.
Тело — из примера спецификации или по схеме: JSON и XML — --data-raw, формы — --data-urlencode, multipart — -F (файловые поля — -F 'file=@./file.bin'), двоичные данные — --data-binary @./body.bin.
Авторизация: Bearer и OAuth 2 — заголовок Authorization: Bearer $TOKEN, Basic — -u "$USERNAME:$PASSWORD", ключ API — заголовок, параметр запроса или cookie с $API_KEY.
Значения в одинарных кавычках экранируются, поэтому команды безопасно вставлять в bash и zsh.

Важно перед запуском

Файл можно запустить целиком (bash orders.sh), но тогда выполнятся все запросы подряд, включая создание и удаление данных. Запускайте команды по одной и только на тестовом стенде, пока не убедитесь в результате.

Вопросы и ответы

Как запустить в Windows? Удобнее всего в Git Bash или WSL. В PowerShell curl — это псевдоним другой команды: вызывайте curl.exe и учитывайте, что кавычки и перенос строки (\) в PowerShell работают иначе.

Нужна коллекция для Postman? Её даёт соседний пункт меню — см. «OpenAPI в Postman».

Откуда берутся значения параметров? Из example и examples спецификации; если их нет — по схеме: первое значение enum, default или типовое значение формата (uuid, date-time, email). Чем подробнее примеры в спецификации, тем точнее команды — см. «Редактор Swagger онлайн».