Usage with the CLI¶
Introduction¶
oasapi offers a command line interface (CLI) to run core operations:
$ python -m oasapi
Usage: python -m oasapi [OPTIONS] COMMAND [ARGS]...
These are common operations offered by the oasapi library
Options:
--help Show this message and exit.
Commands:
filter Filter the SWAGGER operations based on tags, operation path or...
prune Prune from the SWAGGER unused global...
validate Validate the SWAGGER according to the specs.
All these operation are also available programmatically through the oasapi package.
Alternatively to the syntax herebove, you can call oasapi through the oasapi script:
$ oasapi
Usage: oasapi [OPTIONS] COMMAND [ARGS]...
These are common operations offered by the oasapi library
Options:
--help Show this message and exit.
Commands:
filter Filter the SWAGGER operations based on tags, operation path or...
prune Prune from the SWAGGER unused global...
validate Validate the SWAGGER according to the specs.
And there is also a docker image sdementen/oasapi offering the same script through docker run sdementen/oasapi
Help is available with the --help option:
$ oasapi --help
Usage: oasapi [OPTIONS] COMMAND [ARGS]...
These are common operations offered by the oasapi library
Options:
--help Show this message and exit.
Commands:
filter Filter the SWAGGER operations based on tags, operation path or...
prune Prune from the SWAGGER unused global...
validate Validate the SWAGGER according to the specs.
$ oasapi validate --help
Usage: oasapi validate [OPTIONS] SWAGGER
Validate the SWAGGER according to the specs.
SWAGGER is the path to the swagger file, in json or yaml format. It can be
a file path, an URL or a dash (-) for the stdin
Options:
-v, --verbose Make the operation more talkative
-s, --silent Do not print the oasapi messages to stderr
-o, --output FILENAME Path to write the resulting swagger ('-' for stdout)
--help Show this message and exit.
Specifying an OAS 2.0 (aka swagger) file¶
The oasapi commands will often require an OAS 2.0 Document (aka swagger). The swagger can be given in JSON or YAML format and can be a local file or a URL.
Example of usage (YAML file)
$ oasapi validate samples/swagger_petstore.yaml
The swagger is valid.
Example of usage (JSON file):
$ oasapi validate samples/swagger_petstore.json
The swagger is valid.
Example of usage (JSON URL)
$ oasapi validate http://petstore.swagger.io/v2/swagger.json
The swagger is valid.
Pipelining commands¶
When using oasapi in pipes, the - denotes the stdin/stdout.
To pipe a swagger in a command, you replace the path/URL of the swagger with a -:
$ curl -s http://petstore.swagger.io/v2/swagger.json | oasapi validate -
The swagger is valid.
To send the output swagger of a command to stdout, you replace the path for the --output argument with a -
(when using stdout, the format is always YAML).
If you want to silence the commands (ie not sending their message to stderr), you can add the silent argument (-s)
For instance, the following command will:
- get a swagger with curl
- filter it to keep only the operations with the tag ‘pet’
- prune it of any unused elements
- validate it and send it to stdout
$ curl -s http://petstore.swagger.io/v2/swagger.json | oasapi filter -s --tag pet - --output - | oasapi prune -s - --output - | oasapi validate -s - -o -
swagger: '2.0'
info:
description: 'This is a sample server Petstore server. You can find out more about
Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For
this sample, you can use the api key `special-key` to test the authorization filters.'
version: 1.0.3
title: Swagger Petstore
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
...
Validating an OAS 2.0 Document¶
Validating is an operation that will check the swagger for errors:
- structural errors, i.e. errors coming from the swagger not complying with the swagger JSON schema
- semantic errors, i.e. errors beyond the structural ones (e.g. duplicate operationIds)
You can validate a document with the validate command:
$ oasapi validate --help
Usage: oasapi validate [OPTIONS] SWAGGER
Validate the SWAGGER according to the specs.
SWAGGER is the path to the swagger file, in json or yaml format. It can be
a file path, an URL or a dash (-) for the stdin
Options:
-v, --verbose Make the operation more talkative
-s, --silent Do not print the oasapi messages to stderr
-o, --output FILENAME Path to write the resulting swagger ('-' for stdout)
--help Show this message and exit.
$ oasapi validate samples/swagger_petstore.json
The swagger is valid.
$ oasapi validate samples/swagger_petstore_with_errors.json
The swagger is not valid. Following 6 errors have been detected:
- Duplicate operationId @ 'paths./pet/findByStatus.get.operationId' -> the operationId 'updatePet' is already used in an endpoint.
- Json schema validator error @ 'info' -> 'notvalidinfo' does not match any of the regexes: '^x-'
- Json schema validator error @ 'paths./pet.post' -> 'responses' is a required property
- Json schema validator error @ 'paths./pet/findByStatus.get.security.0.petstore_auth' -> 1 is not of type 'array'
- Json schema validator error @ 'schemes.1' -> 'ftp' is not one of ['http', 'https', 'ws', 'wss']
- Security scope not found @ 'paths./pet.put.security.[0].petstore_auth.think:pets' -> scope think:pets is not declared in the scopes of the securityDefinitions 'petstore_auth'
Filtering an OAS 2.0 Document¶
Filtering is an operation that will keep from the swagger only the operations that do match criteria:
- tags: the operation should have at least one tag from a given list of tags (e.g. [“pet”, “store”])
- operations: the VERB + PATH should match a regexp from a list (e.g. [“POST /pet”, “(GET|PUT) /pet/{petId}”])
- security scopes: the operation should be accessible only with the scopes in a given list of scopes (e.g. [“read:pets”])
You can filter a document with the filter command:
$ oasapi filter --help
Usage: oasapi filter [OPTIONS] SWAGGER
Filter the SWAGGER operations based on tags, operation path or security
scopes.
SWAGGER is the path to the swagger file, in json or yaml format. It can be
a file path, an URL or a dash (-) for the stdin
Options:
-v, --verbose Make the operation more talkative
-s, --silent Do not print the oasapi messages to stderr
-o, --output FILENAME Path to write the resulting swagger ('-' for
stdout)
-t, --tag TEXT A tag to keep
-p, --path TEXT A path to keep
-sc, --security-scope TEXT A security scope to keep
--help Show this message and exit.
$ oasapi filter samples/swagger_petstore.json -t pet -t store -sc read:pets -p "POST /pet" -p "(GET|PUT) /pet/{petId}" -o swagger_filtered.yaml
The swagger has filtered or removed the following 19 operations:
- Operation removed as no filter matched. @ 'paths./pet.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet.put' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet/findByStatus.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet/findByTags.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet/{petId}.delete' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet/{petId}.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./pet/{petId}/uploadImage.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./store/inventory.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./store/order.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./store/order/{orderId}.delete' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./store/order/{orderId}.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/createWithArray.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/createWithList.post' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/login.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/logout.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/{username}.delete' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/{username}.get' -> The operation has been removed as it does not match any filter.
- Operation removed as no filter matched. @ 'paths./user/{username}.put' -> The operation has been removed as it does not match any filter.
As the filter command may remove operations, it is a good idea to follow it with a prune command to remove any elements of the swagger
that would not be used anymore.
For instance, the following command filter the swagger to keep only operations with the tag ‘weird’ and prune the resulting swagger afterwards. As no operation has the tag ‘weird’, the filtering leads to a swagger with no more paths and the pruning will clean the swagger showing at the end an almost empty swagger.
$ oasapi filter samples/swagger_petstore.json -t weird -o - 2> filter_messages | oasapi prune - -o - 2> prune_messages
swagger: '2.0'
info:
description: 'This is a sample server Petstore server. You can find out more about
Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For
this sample, you can use the api key `special-key` to test the authorization filters.'
version: 1.0.0
title: Swagger Petstore
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
host: petstore.swagger.io
basePath: /v2
schemes:
- https
- http
paths: {}
externalDocs:
description: Find out more about Swagger
url: http://swagger.io
The operation must match all the three different filter criteria (tags, security scopes and operations regexp) when given.
If you want to apply more advanced filter (like “(tag=’pet’ AND security-scope=’read:pets’) or (tag=’store’)”), you can call the filter
method directly from python and pass these filters (see oasapi.filter()).
Pruning an OAS 2.0 Document¶
Pruning is an operation that will ‘clean’ the swagger by removing any unused elements:
- global definitions not referenced
- global parameters not referenced
- global responses not referenced
- securityDefinitions not used
- securityDefinitions oauth2 scopes not used
- tags not used
- empty paths (endpoints with no verbs attached)
You can prune a document with the prune command:
$ oasapi prune --help
Usage: oasapi prune [OPTIONS] SWAGGER
Prune from the SWAGGER unused global definitions/responses/parameters,
unused securityDefinition/scopes, unused tags and unused paths.
SWAGGER is the path to the swagger file, in json or yaml format. It can be
a file path, an URL or a dash (-) for the stdin
Options:
-v, --verbose Make the operation more talkative
-s, --silent Do not print the oasapi messages to stderr
-o, --output FILENAME Path to write the resulting swagger ('-' for stdout)
--help Show this message and exit.
$ oasapi prune samples/swagger_petstore.json
The swagger had no unused elements.
$ oasapi prune samples/swagger_petstore_unused_elements.json
The swagger has been pruned of 5 elements:
- Oauth2 scope removed @ 'securityDefinitions.petstore_auth.scopes.write:pets' -> oauth2 scope not used
- Path is empty @ 'paths./store/inventory' -> path '/store/inventory' has no operations defined
- Reference filtered out @ 'definitions.User' -> reference not used
- Security definition removed @ 'securityDefinitions.api_key' -> security definition not used
- Tag definition removed @ 'tags.[2]' -> tag definition for 'user' not used