Automated Testing and Documentation for your REST API
Project description
A library for your API that provides:
- Automated Integration Testing
- Automated Live Documentation
Contents
Requirements
How to install
$ pip install scanapi
Basic Usage
You will need to write the API's specification and save it as an YAML or JSON file.
api:
endpoints:
- name: scanapi-demo
path: http://demo.scanapi.dev/api/
requests:
- name: list_all_devs
path: devs/
method: get
And run the scanapi command
$ scanapi -s <file_path>
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 PATH
-c, --config-path PATH
-r, --reporter [console|markdown|html]
-t, --template PATH
--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 |
endpoints | It represents a list of API endpoints | list | endpoint |
headers | The HTTP headers | dict | endpoint, request |
method | The HTTP method of the request (GET, POST, PUT, PATCH or DELETE). If not set, GET will be used | string | request |
name | An identifier | string | endpoint, request |
path | A part of the URL path that will be concatenated with possible other paths | string | endpoint, request |
requests | It represents a list of HTTP requests | list | endpoint |
vars | Key used to define your custom variables to be used along the specification | dict | endpoint, 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 an environment variable | string | endpoint, request |
${{python_code}} | A syntax to get the value of a Python code expression | string | request |
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:
endpoints:
- name: scanapi-demo
path: ${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
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: ${{response.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
API specification in multiple files
With !include
, it is possible to build your API specification in multiple files.
For example, these two files
# api.yaml
api:
endpoints:
- name: scanapi-demo
path: ${BASE_URL}
requests: !include include.yaml
# include.yaml
- name: health
path: /health/
would generate:
api:
endpoints:
- name: scanapi-demo
path: ${BASE_URL}
requests:
- name: health
path: /health/
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.
report:
hide-request:
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.
In the same way you can omit sensitive information from response.
report:
hide-response:
headers:
- Authorization
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 :)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.