contractor

Contractor - HTTP API testing tool

Contractor читает спецификацию вашего API чтобы:

1. Создать mock-сервер
2. Валидировать backend-имплементацию

Поддерживаемые форматы спецификации API:

1. OpenAPI 2 (также известный как Swagger)
2. OpenAPI 3

Поддерживаемые расширения файлов спецификации API:

1. YAML
2. JSON

Поддерживаемые платформы:

1. macOS
2. linux
3. windows

Установка

С помощью go install:

go install github.com/byorty/contractor/cmd/...

С помощью Homebrew:

brew install byorty/tap/contractor 

Быстрый старт

1. Опишите ваше API например в формате OpenAPI 2:

   swagger: "2.0"
   info:
     title: Test API
     version: "1.0"
   schemes:
     - https
   consumes:
     - application/json
   produces:
     - application/json
   paths:
     # ...
     # описание других методов API
     # ...
     /v1/users/{user_id}/news/{news_id}:
       patch:
         operationId: Users_ChangeUserNews
         responses:
           "200":
             description: A successful response.
             schema:
               $ref: '#/definitions/UserNews'
         parameters:
         - name: user_id
           in: path
           required: true
           type: integer
           format: int64
         - name: news_id
           in: path
           required: true
           type: integer
           format: int64
         - name: body
           in: body
           required: true
           schema:
              $ref: '#/definitions/ChangeUserNewsRequestParams'
         tags:
         - Users
   definitions:
     # ...
     # описание сущностей API
     # ...
   

2. Добавьте расширение x-examples:

   /v1/users/{user_id}/news/{news_id}:
     get:
       operationId: Users_ChangeUserNews
       # ...
       # описание метода API
       # ...
       x-examples: относительный/путь/до/примеров/запросов/и/ответов.yml
   

3. Опишите примеры запросов и ответов метода API:

   CHANGE_USER_NEWS_SUCCESS:                        # уникальное имя в рамках всей спецификации
     priority: 1                                    # приоритет
     tags:                                          # поддержка тэгов
       - user                                       #
       - develop                                    #
       - production                                 #
     request:                                       # описание запроса
       headers:                                     # описание заголовков запроса
         Authorization: ${VAR_AUTHORIZATION}        # поддержка переменных
       parameters:                                  # описание параметров запроса
         user_id: 472                               # имена задаются так, как описаны в спецификации API
         news_id: 11401                             #
         body:                                      # описание тела запроса для POST, PUT, PATCH запросов
           is_viewed: true                          #
           reaction: USER_NEWS_REACTION_LIKE        #
     response:                                      # описание ответа
       status_code: 200                             # статус обязателен
       body:                                        # описание тела ответа
         id: eq(30676003)
         user:
           id: eq(472)
         news:
           id: eq(11401)
           title: >
             eq('Домашняя работа: как стартап бывшего топ-менеджера Microsoft зарабатывает на покупке жилья за наличные')
           annotation: regex('([\\w\\d\\-\\.\\,\\?\\:]){100}')
           partner: empty()
           content: regex('([\\w\\d\\-\\.])')
           hash: eq('ee43501beb0944c412c9580ae604546f')
           preview_img: eq('977081c0dc136761a13d60c513437dbf')
           tags: empty()
           status: eq('NEWS_STATUS_ACTIVE')
           type: eq('CONTENT_TYPE_NEWS')
           # ...
           # описание свойств ответа
           # ...
   

4. Создайте mock-сервер:

   contractor  -m mock \
               -s ./specs/oa2.yml \
               -u http://localhost:8181 \
               -f oa2 \
               -v "VAR_AUTHORIZATION: Bearer some-jwt"
   

5. Провалидируйте свой сервер:

   contractor  -m test \
               -s ./specs/oa2.yml \
               -u http://localhost:8181 \
               -f oa2 \
               -t tag1 \
               -t tag2 \
               -v "VAR_AUTHORIZATION: Bearer some-jwt"
   

Использование

contractor [OPTIONS]

Аргументы командной строки

-m, --mode: обязательный, режим работы contractor, возможные значения:

1. test - валидация API по указанной спецификации
2. mock - создание mock-сервера по указанной спецификации

-s, --spec-filename: обязательный, путь по спецификации API

-f, --spec-format: опциональный, формат спецификации API, возможные значения:

1. oa2 - для OpenAPI 2, значение по умолчанию
2. oa3 - для OpenAPI 3

-u, --url: обязательный, хост и порт, на котором работает имплементация вашего API, либо должен работать mock-сервер

-v, --variable: опциональный, переменные доступные в примерах запросов и ответов

-t, --tags: опциональный, список тэгов

-c, --cert-filename: опциональный, путь до сертификата, если mock-сервер должен работать по https

-k, --key-filename: опциональный, путь до ключа, если mock-сервер должен работать по https

Список функций