marketsquare/roboswag

Roboswag

• Introduction
• Installation
• Usage
• Limitations

Introduction

🤖 Roboswag is a tool that automatically generates Python libraries out of your Swagger (OpenAPI specification file). These libraries can be used to create tests with various payload content and its validation. It also supports response validation against schema and verification of different status codes.

Note

The tool is in the Alpha state, which means it may be unstable and should be used at your own risk. Some features may be broken and there are still many things to be developed. Happy testing!

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs. Click here for v3 documentation and here for v2 documentation.

Hosted on GitHub. 🎖️

Installation

You can install Roboswag simply by running::

pip install roboswag

Usage

Roboswag can be easily run from command line. To check if it's installed, run this to see the current version:

roboswag -v

To execute Roboswag with its full capabilities, run it with provided path to the Swagger (OpenAPI specification) file:

roboswag generate -s <path_to_swagger>

You can try out the tool using the example of swagger file located in swaggers/petstore.json.

Successful execution should result in printing the information about generated files and a whole new directory (named by the value of info.title from your Swagger file) consisting of:

• endpoints directory with files representing each tag as a class with methods representing its endpoints,
• models directory with API models represented as Python classes,
• schemas directory with every possible schema from your API as JSON file used for validating payload and responses.

Now you can just create a test file, import desired endpoint and start automating the testing!

Limitations

The tool is already able to generate libraries but...

• Not all fields from the swagger specification may be supported. This means that a specific file may break the tool and flood the terminal with stack trace (we will be really grateful to receive bug issues in our Github project!)
• Authorization to access the API is not yet fully covered
• There is not much to be configured here - it always works the same
• There is no real documentation apart from this file

Please be forgiving and submit an issue, if you struggle with something or just contact us on our Slack channel. It's more than welcome also to support us by code contribution! ⌨️

roboswag's Issues

Run black on generated output

Could it be possible to run black from python on generated class? We're trying to match the format using Jinja templates (and it even spread in multi lines if line is too long) but it's still not perfect. We can minimize the effort on our side if we were able to use external formatter (ie the whole get_python_method_signatur in endpoint.py could be a lot less complex).

PIP installation problem

Hi Guys,

I wanted to give you library a try in one of my API projects. Unfortunately after installation with pip, during verification I am receiving following error message:

Can you please give me a hint if there are any missing steps in pip installation process or should I do some investigation on my environment?

ProxyError: Cannot connect to proxy

Dear Mateusz,

thank you for your hard work and contributions to the RF community!

we were beyond excited to try the tool at work, however I am having issues to make the SwaggerPetshop example to work. I am not able to connect to proxy from the company's laptop (while having heavy security measurements in place).

Using OperatingSystem's Set Environment Variable to set both HTTP_PROXY and HTTPS_PROXY within the test case does not seem to work either.

The error:
ProxyError: HTTPSConnectionPool(host='petstore3.swagger.io', port=443): Max retries exceeded with url: /api/v3/pet/findByStatus?status=available (Caused by ProxyError('Cannot connect to proxy.', FileNotFoundError(2, 'No such file or directory')))

Thank you for looking into this,
Tereza

Skeleton of test framework

We need to define way of testing our tool.

Release workflow

It does include changelog file, PyPI API token for publishing packages and Github Action on releases.

Nullable values support

ValidationError: None is not of type 'string'

Failed validating 'type' in schema['properties']['timeRemoved']:
    {'format': 'date-time', 'nullable': True, 'type': 'string'}

On instance['timeRemoved']:
    None

I have schema that suggests the value of this field should be allowed to be null/None but the schema validator fails on it. Is this expected behavior right now?

requestBody in OpenAPI v3

OpenAPI v3 uses requestBody for in body parameters instead of in:body used in OpenAPI v2.

Default exp_status is always 200

We should take it from specs - for example if endpoint is using POST and have 201 in responses, 201 should be used instead as default exp_status.

We should not validate response description

We are using endpoint responses description field to generate validators:

          "400": {
            "description": "Invalid username supplied"

self.validate.response_as_text(response, "Invalid username supplied")

It's not valid - we can validate schema but we should not use description field for validation.

Tags are optional but roboswag fails on missing tags

Editied - I was under wrong impression how the code works. We're parsing the endpoints and then using tag attribute to store them in unique list. If the tags are missing, the code will fail. It still requires deeper analysis.

Setup file & required dependencies

Configuration file support

Load pyproject.toml with tool.rfopenapi section and add a custom config file parser.

Roboswag not running while using other than the example file

Dear authors,
I've also encountered an issue while running roboswag -s using a path to a swagger file used within our company.
The version of OpenAPI specification is v2, so hopefully the .json file should be supported by roboswag.
Please see the stackTrace below:

Traceback (most recent call last):
  File "C:\Program Files\Python397\lib\runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Program Files\Python397\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\Scripts\roboswag.exe\__main__.py", line 7, in <module>
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\__main__.py", line 27, in run_roboswag
    generate_cli()
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\__main__.py", line 23, in generate_cli
    generate(args.spec)
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\generate\generate.py", line 13, in generate
    api_model, swagger = APIModelCreator.from_prance(source)
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\generate\models\api.py", line 123, in from_prance
    api_model.parse_swagger(swagger)
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\generate\models\api.py", line 27, in parse_swagger
    self.parse_definitions(swagger)
  File "C:\Users\cen69317\AppData\Roaming\Python\Python39\site-packages\roboswag\generate\models\api.py", line 96, in parse_definitions
    for prop_name, prop_body in def_body.get("properties", []).items():
AttributeError: 'list' object has no attribute 'items'

I'll be happy to send you the file in case you would be open to look into this.

Thank you for your effort,
Tereza Chudobová

Schema should be loaded from the file and not embedded

Currently we're embedding schemas in our endpoint definitions. It bloats Python files and make it harder to navigate through them. If several endpoints use the same schema, you need to modify it in multiple places.

We should use path to schema instead - we're already preserving schema json files.

Pagination methods

They should be easily configurable for custom pagination methods.

Command line interface

Using argparse.

Support for OpenAPI v3

The APIModel class only supports OpenAPI version 2, while prance that is used for parsing the API is able to analyze also v3. We need to add different methods for parsing swagger v3.

Handle invalid schema

It should output user friendly message with schema validation errors.

Automatically built documentation

To be considered either reusing Robocop/Robotidy way of doing it (readthedocs) or hosting the docs using Github Pages / other option for generating html files (if not Sphinx).

POC of API to be used in testing

It can be defined using FastAPI. It would be good to have easy way of running the API locally (ie with docker) and invoke tasks (or other) for generating swagger documentation that can be later on used in tool development.

Pass either model object or dictionary to the body parameter

At this moment, the body parameter only accepts dictionary, which can be optionally validated by providing a boolean value for validate_payload parameter. The endpoint methods should also accept providing the payload using an object that later can be serialized into a dictionary.

Extend logging

Logging should be configurable (or add more separate Logger classes that could be used instead). Logging should be good enough so it's clear how we're interacting with API.

Support for API from JSON and YAML

Check if both of these formats are parsed correctly.

Compare schema

Generate endpoint classes with the option of veryfing response schema. For example given this swagger:

  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

we could generate following mapping:

responses = {
    "200": Pet
    "default": "ErrorModel"
}
And if "verify_schema" is set to True (default True) it would verify the received response schema.

More auth classes

Particularly Oauth2 support (or any other popular auth in API).

ValidationError with Swagger Petstore v3 specification

Hello,

I just started to play around with this library and took Open API Petstore v3 as my starting point. Now when trying to generate code I get:
prance.ValidationError: Version mismatch: selected backend "flex" does not support specified version 3.0.2!

Spec I'm using:
https://petstore3.swagger.io/ --> https://petstore3.swagger.io/api/v3/openapi.json

I also tried to validate spec by calling prance directly and got same error:

$ prance.exe validate petstore_v3.json
Processing "petstore_v3.json"...
 -> Resolving external references.
ERROR in "petstore_v3.json" [ValidationError]: Version mismatch: selected backend "flex" does not support specified version 3.0.2!

But when changing backend to 'openapi-spec-validator' it works fine.

$ prance.exe validate --backend openapi-spec-validator petstore_v3.json
Processing "petstore_v3.json"...
 -> Resolving external references.
Validates OK as OpenAPI 3.0.2!

-> prance seems to use flex as default backend if flex lib is installed.
--> So the question is: should roboswag library use 'openapi-spec-validator' as backend instead of 'flex' in case of v3 spec? Or am I missing something here?
See also: https://prance.readthedocs.io/en/latest/#compatibility

Github actions for veryfing commits

Since for now the repository is private we can only create files without running actions themselves.