Extract

The definition extract command is used to extract information from the specified OpenAPI definition.

As the OpenAPI specification is in either YAML or JSON format it is not conducive for extraction as a simple CSV list required by many tools and processes.

The qaskx-cli def extract --category ^^type (*list)^^ --spec ^^URL^^ command is there to assist you. No need to manually map or transcribe information in the OpenAPI document. Just include all the relevant information in the OpenAPI and then you can use it in server, client code generation and as input to other documentation tools.

The basic information extract for example includes the field types and their minimum and maximum lengths allowed if specified.

Usage: qaskx-cli def extract --category=<category> [-k=<key>] [-d=<devops file>] [-s=<openAPI file>] [-o=<output file>] [--validate] [--overwrite] [-v] [-c=<conf file>] [--silent] [--colourCLI] [--offline]

Extract from OpenAPI document

Options:
  -d, --devops      devops.json file path
  -s, --spec        OpenAPI file to parse for extraction
      --category    Category to extract
  -k, --key         Category key to extract
  -o, --output      Output file name
      --validate    Validate API definition
      --overwrite   Overwrite existing file
  -v, --verbose     Verbose logging
      --silent      Silent running
      --colourCLI   Colour terminal and command line (env $QASKX_COLOUR_CLI)
  -c, --conf        Configuration file (env $QASKX_CONFIG_FILE)
      --offline     Offline mode (env $QASKX_OFFLINE)

Category

You can extract various portions of the OpenAPI specification by supplying a category values.

Valid values are:

  • info: the basic information in the header portion of the specification
  • path: the routes published by the specification
  • server: the list of servers
  • security: the list of security schemes supported
  • prepath: this is the leading path before the routes
  • basic: basic specification information

Key

The key parameter allows filtering of the results based on description. The filtering is based on a regex comparison so complex queries can be constructed.

For the basic information extract the key takes special construction values.

For basic extracts the key can take the following forms:

Scope Format Values Sample
path path=<value> regex format –key path=^/user/.*
method method=<value> POST, GET, PUT, PATCH, DELETE, etc –key method=POST
status status=<value> integer –key status=200
OperationID operationid=<value> regex format –key operationid=^getuser.*

For complex queries and filtering, please output to CSV file and apply filtering rules to the data in the file.

Examples

The following example commands will extract information from the OpenAPI specification.

If you use the options --silent you get a simple tab (\t) delimited listing that can be ingested for processing. You can also include the option --output <filename.csv> which will create a CSV formatted file containing the extract information.

qaskx-cli definition extract --category info --spec https://petstore3.swagger.io/api/v3/openapi.json
qaskx-cli definition extract --category path --spec https://petstore3.swagger.io/api/v3/openapi.json
qaskx-cli definition extract --category server --spec https://petstore3.swagger.io/api/v3/openapi.json
qaskx-cli definition extract --category security --spec https://petstore3.swagger.io/api/v3/openapi.json
qaskx-cli definition extract --category prepath --spec https://petstore3.swagger.io/api/v3/openapi.json
qaskx-cli definition extract --category basic --spec https://petstore3.swagger.io/api/v3/openapi.json

The extract is also possible using the docker image.