Swama: CLI-инструмент для работы с Swagger/OpenAPI16.09.2024 19:30

Если вы работаете с API, вы наверняка сталкивались с OpenAPI или Swagger для описания ваших API-спецификаций. Хотя эти инструменты облегчают процесс документирования, порой работать с ними через графические интерфейсы или ручной просмотр YAML-файлов бывает неудобно и утомительно.

Здесь на помощь приходит Swama — CLI-инструмент, позволяющий взаимодействовать с API-спецификациями напрямую из терминала. Он упрощает просмотр, фильтрацию и тестирование ваших API с использованием Swagger или OpenAPI.

Что такое Swama?

Swama — это командная утилита, созданная для взаимодействия со спецификациями Swagger/OpenAPI. Она позволяет:

  • Листать и просматривать все доступные API-эндпоинты.

  • Преобразовывать эндпоинты в команды curl или fetch для быстрого тестирования.

  • Фильтровать эндпоинты по HTTP-методу, тегам и путям.

  • Исследовать теги и серверы, указанные в спецификации API.

  • {todo} Редактирование данных и экспорт в yaml/json

  • {todo} Запус mock-сервера

  • {todo} Команды для отправки запросов на api

Основные возможности

  • Список API-эндпоинтов: Получите полный список всех доступных API-методов и их путей.

  • Просмотр эндпоинтов: Подробно изучите каждый метод, его параметры, тело запроса и ответы.

  • Конвертация в curl/fetch: Преобразуйте эндпоинты в команды curl или fetch для быстрого тестирования.

  • Работа с тегами и серверами: Легко просматривайте и управляйте тегами и серверами в спецификации API.

Установка

Swama доступна как в виде предварительно собранных бинарных файлов, так и в виде исходного кода, который вы можете собрать самостоятельно.

Установка с помощью бинарных файлов

  1. Перейдите на страницу релизов и скачайте последнюю версию для вашей операционной системы.

  2. Добавьте бинарный файл в переменную окружения $PATH:

    • Linux/MacOS: 

      sudo mv swama /usr/local/bin/
sudo chmod +x /usr/local/bin/swama

    • Windows: Добавьте файл в системный PATH для глобального доступа.

Сборка из исходников

Вы также можете собрать Swama вручную: 

git clone https://github.com/idsulik/swama
cd swama
go build -o swama

Пример использования

После установки Swama можно начинать взаимодействовать с вашими Swagger/OpenAPI файлами через командную строку.

Список эндпоинтов

Для того чтобы получить полный список всех эндпоинтов, используйте следующую команду: 

swama endpoints list --file swagger.yaml

Вы также можете фильтровать эндпоинты по методу, тегам или конкретным путям: 

swama endpoints list --method GET --tag user
# если не указан "--flag", то будет сделана попытка найти файл в текущей директории

Просмотр информации об эндпоинте

Чтобы получить подробную информацию о конкретном эндпоинте, включая HTTP-метод, тело запроса и возможные ответы, используйте команду: 

swama endpoints view --endpoint /user --method GET

a9523ff105e34b5b17d27e6ce570122b.png

Конвертация эндпоинта в команду curl или fetch

Одной из ключевых функций Swama является возможность конвертации эндпоинтов в команды curl или fetch для тестирования: 

swama endpoints convert --file swagger.yaml --endpoint /api/users --method POST --type curl

Общая информация о Swagger/OpenAPI файле

Команда info позволяет быстро получить основную информацию о вашем Swagger/OpenAPI файле, такую как версия, заголовок и описание API.: 

swama info view

e7c53160e5ca1c51a59d028bb3b239e0.png

Список серверов

Команда servers list выводит список всех серверов, определенных в Swagger/OpenAPI файле, включая их URL и описание. Это может быть полезно, если у вас есть несколько окружений, таких как тестовое, staging или production: 

swama servers list

Список тегов

Теги в API используются для группировки эндпоинтов. Команда tags list выводит все теги, указанные в спецификации API: 

swama tags list

fe3da83f5253e2983eb328829e707992.png

Автодополнение

Swama поддерживает автодополнение для командной строки, что позволяет ускорить работу с инструментом. Чтобы включить автодополнение, выполните следующие команды:

Заключение

Swama значительно упрощает работу с API-спецификациями. Теперь, вместо того чтобы вручную искать нужные эндпоинты в Swagger UI или постоянно писать команды curl, вы можете сделать всё это прямо из вашего терминала.

p.s. напишите в комментариях свои идеи, как можно улучшить инструмент, чтобы он стал еще удобнее и полезнее. Спасибо!

© Habrahabr.ru