aPing

A simple API Ping tool to feed a Swagger/OpenAPI 3.0 document file, call all paths and record time and responses, e.g. to benchmark an endpoint.

Features

Read Swagger/OpenAPI 3.0 api definition files and call all paths
Ping all paths in parallel workers and/or over several loops
Pass custom headers, e.g. Authorization
Create random integer and string parameters for urls
Track the time and response body per request
Output the results to console, CSV, HTML, JSON or Markdown

Latest Versions

0.4.0
- Added regular expression filter option for paths
- Added response time milliseconds threshold
0.3.0
- Added average ms calculation for multiple loops
- Added Bootstrap HTML template with sortable table
- Added JSON output
0.2.0
- Added an option to configure included query methods

Download the latest release here.

Usage

For a quick start download a release, change into the directory and execute the binary with your options, e.g.:

./aping -input="calls.json" -header='{\"Authorization\": \"Bearer eyXYZ\"}' -response -base=http://localhost:8080/api -out=html -l=5 -w=5

Example progress output:

Pinging 'REST API Documentation - Backend'
Pinging 122 routes (Round 1) ... done! [122 in 11.586s]
Pinging 122 routes (Round 2) ... done! [122 in 23.315s]
Pinging 122 routes (Round 3) ... done! [122 in 37.262s]
Pinging 122 routes (Round 4) ... done! [122 in 48.616s]
Pinging 122 routes (Round 5) ... 27.9% ║█████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░║ [34 in 1m1.386s]

Options

Usage
  -input string
        *The path/url to the Swagger/OpenAPI 3.0 input source
  -base string
        The base url to query
  -header string
        Pass a custom header as JSON string, e.g. '{\"Authorization\": \"Bearer TOKEN\"}' (default "{}")
  -loop int
        How often to loop through all calls (default 1)
  -out string
        The output format. Options: console, csv, html, md, json (default "console")
  -response
        Include the response body in the output
  -timeout int
        The timeout in seconds per request (default 5)
  -worker int
        The amount of parallel workers to use (default 1)
  -methods string
        An array of query methods to include, e.g. '[\"GET\", \"POST\"]' (default "[\"GET\",\"POST\"]")
  -threshold int
        Only collect pings above this response threshold in milliseconds (default -1)
  -filter string
        A regular expression to filter paths. Only matches will be pinged!

Input

Reference a file input somewhere reachable by your machine. References in the OpenAPI specification can be resolved if absolute or relative to the main file.

Base

Pass a base url such as http://localhost:8080/api. If non is given the servers array of the OpenAPI specification will be presented to pick a server from.

Header

Pass custom headers to send with every request as an escaped JSON string such as '{\"Authorization\": \"Bearer eyXYZ\"}'.

The default headers are

"Accept":       "*/*"
"Connection":   "Keep-Alive"
"Content-Type": "application/json"
"User-Agent":   "aPing"

You can override these options by passing the same key.

Worker

How many parallel processes should be spawned to query your endpoints.

Ensure that your endpoint can handle multiple requests, otherwise multiple workers might run into the timeout.

Output

Define an output format. The output is written to a local aping.XYZ file, depending on your choice.

The output contains (at most):

The pinged path
The effective URLs (base + path)
The query method
The average milliseconds
The responses

Some data is only available with their according flags, i.e. loop and response

Loop

If loop > 1 is mixed with response all responses are logged, if the path has parameters!

Build

Download and install Golang for your platform.

Clone this repository and build your own version:

git clone https://github.com/elipZis/aPing.git
go build -o aping github.com/elipZis/aPing

Compatibility

aPing has been tested under the following conditions

Windows 10 Professional (64-bit)

Missing/Upcoming Features

aPing is not fully-fledged (yet). Some functionality is missing and errors may occur.

Known issues are:

Paths having request bodies are not pinged
Parameters besides integer and string are not pinged

License and Credits

aPing is released under the MIT license by elipZis.

This program uses multiple other libraries. Credits and thanks to all the developers working on these great projects:

Swagger/OpenAPI 3.0 parser kin-openapi
Pretty console printer go-pretty

Disclaimer

This source and the whole package comes without a warranty. It may or may not harm your computer. Please use with care. Any damage cannot be related back to the author. The source has been tested on a virtual environment and scanned for viruses and has passed all tests.