scanapi 0.0.18

Automated Testing and Documentation for your REST API

ScanAPI

A library for your API that provides:

• Automated Integration Testing
• Automated Live Documentation

Contents

• Requirements
• How to install
• Basic Usage
• Documentation
  • ScanAPI CLI
  • API Specification Keys
  • Environment Variables
  • Custom Variables
  • Python Code
  • Chaining Requests
  • Configuration File
  • Hiding sensitive information
• Contributing

Requirements

• pip

How to install

$ pip install scanapi

Basic Usage

You will need to write the API's specification and save it as api.yaml.

api:
  base_url: http://scanapi.dev/demo/api/
  requests:
    - name: list_all_devs
      path: devs
      method: get

And run the scanapi command

$ scanapi

Then, the lib will hit the specified endpoints and generate a scanapi-report.md file with the report results

You can find a complete example of a demo project using ScanAPI at scanapi-demo!

Documentation

ScanAPI CLI

$ scanapi --help
Usage: scanapi [OPTIONS]

  Automated Testing and Documentation for your REST API.

Options:
  -s, --spec-path PATH
  -o, --output-path TEXT
  -r, --reporter [console|markdown|html]
  -t, --template TEXT
  --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
  --help                          Show this message and exit.

API Specification Keys

KEY	Description	Type	Scopes
api	It is reserver word that marks the root of the specification and must not appear in any other place	dict	root
body	The HTTP body of the request	dict	request
base_url	The API’s base URL	string	api
endpoints	It represents a list of API endpoints	list	api, endpoint
headers	The HTTP headers	dict	api, endpoint, request
method	The HTTP method of the request (GET, POST, PUT or DELETE)	string	request
name	An identifier	string	endpoint, request
path	A part of the URL path that will be concatenated with the base URL and possible other paths	string	endpoint, request
requests	It represents a list of HTTP requests	list	api, endpoint
vars	Key used to define your custom variables to be used along the specification	dict	request
${custom var}	A syntax to get the value of the custom variables defined at key vars	string	request - after vars definition
${ENV_VAR}	A syntax to get the value of the environment variables defined at .scanapi file	string	api, endpoint, request
${{python_code}}	A syntax to get the value of a Python code expression	string	requests

Environment Variables

You can use environment variables in your API spec file with the syntax

${MY_ENV_VAR}

For example:

$ export BASE_URL="http://demo.scanapi.dev/api/"

api:
  base_url: ${BASE_URL}
  requests:
    - name: health
      method: get
      path: /health/

ScanAPI would call the following http://demo.scanapi.dev/api/health/ then.

Heads up: the variable name must be in upper case.

Custom Variables

Inside the request scope, you can create custom variables using the syntax:

requests:
  - name: my_request
    ...
    vars:
      my_variable_name: my_variable_value

And in the next requests you can access them using the syntax:

${my_variable_name}

Python Code

You can add Python code to the API specification by using the syntax:

${{my_pyhon_code}}

For example

body:
  uuid: 5c5af4f2-2265-4e6c-94b4-d681c1648c38
  name: Tarik
  yearsOfExperience: ${{2 + 5}}
  languages:
    - ruby
      go
  newOpportunities: false

Chaining Requests

Inside the request scope, you can save the results of the resulted response to use in the next requests

requests:
  - name: list_all
    method: get
    vars:
      dev_id: ${{responses.devs_list_all.json()[2]["uuid"]}}

The dev_id variable will receive the uuid value of the 3rd result from the devs_list_all request

It the response is

[
    {
        "uuid": "68af402f-1084-40a4-b9b2-6bb5c2d11559",
        "name": "Anna",
        "yearsOfExperience": 5,
        "languages": [
            "python",
            "c"
        ],
        "newOpportunities": true
    },
    {
        "uuid": "0d1bd106-c585-4d6b-b3a4-d72dedf7190e",
        "name": "Louis",
        "yearsOfExperience": 3,
        "languages": [
            "java"
        ],
        "newOpportunities": true
    },
    {
        "uuid": "129e8cb2-d19c-41ad-9921-cea329bed7f0",
        "name": "Marcus",
        "yearsOfExperience": 4,
        "languages": [
            "c"
        ],
        "newOpportunities": false
    }
]

The dev_id variable will receive the value 129e8cb2-d19c-41ad-9921-cea329bed7f0

Configuration File

If you want to configure the ScanAPI with a file, you can create a .scanapi.yaml file in the root of your project

spec_path: my_path/api.yaml
output_path: my_path/scanapi-report.md
reporter: console

Hiding sensitive information

If you want to omit sensitive information in the report, you can configure it in the .scanapi.yaml file. For now, it is only working for request headers.

report:
  hide:
    headers:
      - Authorization

The following configuration will print all the headers values for the Authorization key for all the request as <sensitive_information> in the report.

Contributing

Collaboration is super welcome! We prepared the CONTRIBUTING.md file to help you in the first steps. Feel free to create new GitHub issues and interact here :)