swagger-conformance


Nameswagger-conformance JSON
Version 0.2.2 PyPI version JSON
download
home_pagehttps://github.com/olipratt/swagger-conformance
SummaryTool for testing whether your API conforms to its swagger specification
upload_time2018-02-12 20:09:16
maintainer
docs_urlhttp://pythonhosted.org/swagger-conformance/
authorOli Pratt
requires_python
licenseMIT
keywords swagger testing openapi hypothesis
VCS
bugtrack_url
requirements hypothesis pyswagger requests
Travis-CI
coveralls test coverage
            swagger-conformance
===================

|PyPI version| |Build Status| |codecov| |docs|

|PyPI Versions| |PyPI License|

You have a Swagger (aka OpenAPI) schema defining an API you provide -
but does your API really conform to that schema, and does it correctly
handle all valid inputs?

``swaggerconformance`` combines the power of ``hypothesis`` for property
based / fuzz testing with ``pyswagger`` to explore all corners of your
API - testing its conformance to its specification.

Purpose
-------

A Swagger/OpenAPI Spec allows you to carefully define what things are
and aren't valid for your API to consume and produce. This tool takes
that definition, and tries to make requests exploring all parts of the
API while strictly adhering to the schema. Its aim is to find any places
where your application fails to adhere to its own spec, or even just
falls over entirely, so you can fix them up.

*This is not a complete fuzz tester of your HTTP interface e.g. sending
complete garbage, or to non-existent endpoints, etc. It's aiming to make
sure that any valid client, using your API exactly as you specify, can't
break it.*

Setup
-----

Either install with ``pip install swagger-conformance``, or manually
clone this repository and from inside it install dependencies with
``pip install -r requirements.txt``.

Usage
-----

After setup, the simplest test you can run against your API is just the
following from the command line:

.. code:: bash

    python -m swaggerconformance 'http://example.com/api/schema.json'

where the URL should resolve to your swagger schema, or it can be a path
to the file on disk.

This basic test tries all your API operations looking for errors. For
explanation of the results and running more thorough tests, including
sequences of API calls and defining your custom data types, `see the
examples <https://github.com/olipratt/swagger-conformance/tree/master/examples>`__.

Documentation
-------------

Full documentation, including the example walkthroughs mentioned above
and API documentation, is `available
here <https://pythonhosted.org/swagger-conformance/index.html>`__.

Wait, I don't get it, what does this thing do?
----------------------------------------------

In short, it lets you generate example values for parameters to your
Swagger API operations, make API requests using these values, and verify
the responses.

For example, take the standard `petstore
API <http://petstore.swagger.io/>`__ example. At the time of writing,
that has an endpoint ``/pet`` with a ``PUT`` method operation that takes
a relatively complicated ``body`` parameter.

With just a little code, we can load in the swagger schema for that API,
access the operation we care about, and generate example parameters for
that operation:

.. code:: python

    >>> import swaggerconformance
    >>>
    >>> client = swaggerconformance.client.Client('http://petstore.swagger.io/v2/swagger.json')
    >>>
    >>> strategy_factory = swaggerconformance.strategies.StrategyFactory()
    >>> operation = client.api.endpoints["/pet"]["put"]
    >>> strategy = operation.parameters_strategy(strategy_factory)
    >>> strategy.example()
    {
      'body':{
        'id':110339,
        'name':'\U00052ea5\x9d\ua79d\x92\x13\U000f7c436!\U000aa3c5R\U0005b40e\n',
        'photoUrls':[
          '\ua9d9\U0003fb3a\x13\U00025c1c\U000974a8\u3497\U000515fa\n',
          "\U000b38a4>*\u6683'\U0002cd8f\x0f\n"
        ],
        'status':'sold',
        'category':{
          'id':-22555826027447
        },
        'tags':[
          {
            'id':-172930,
            'name':'\U000286df\u04dc\U00033563\u696d\U00055ba8\x89H'
          }
        ]
      }
    }
    >>>

See `the
examples <https://github.com/olipratt/swagger-conformance/tree/master/examples>`__
for more details, and how to make requests against an API using these
parameter values.

.. |PyPI version| image:: https://badge.fury.io/py/swagger-conformance.svg
   :target: https://badge.fury.io/py/swagger-conformance
.. |Build Status| image:: https://travis-ci.org/olipratt/swagger-conformance.svg?branch=master
   :target: https://travis-ci.org/olipratt/swagger-conformance
.. |codecov| image:: https://codecov.io/gh/olipratt/swagger-conformance/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/olipratt/swagger-conformance
.. |docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
   :target: https://pythonhosted.org/swagger-conformance/index.html
.. |PyPI Versions| image:: https://img.shields.io/pypi/pyversions/swagger-conformance.svg
   :target: https://pypi.python.org/pypi/swagger-conformance
.. |PyPI License| image:: https://img.shields.io/pypi/l/swagger-conformance.svg
   :target: https://pypi.python.org/pypi/swagger-conformance



            

Raw data

            {
    "_id": null,
    "maintainer": "",
    "docs_url": "http://pythonhosted.org/swagger-conformance/",
    "requires_python": "",
    "maintainer_email": "",
    "cheesecake_code_kwalitee_id": null,
    "keywords": "swagger,testing,OpenAPI,hypothesis",
    "upload_time": "2018-02-12 20:09:16",
    "requirements": [
        {
            "name": "hypothesis",
            "specs": [
                [
                    ">=",
                    "3.4.2"
                ]
            ]
        },
        {
            "name": "pyswagger",
            "specs": [
                [
                    ">=",
                    "0.8.29"
                ]
            ]
        },
        {
            "name": "requests",
            "specs": [
                [
                    ">=",
                    "2.13.0"
                ]
            ]
        }
    ],
    "author": "Oli Pratt",
    "home_page": "https://github.com/olipratt/swagger-conformance",
    "github_user": "olipratt",
    "download_url": "https://pypi.python.org/packages/5d/7b/cc1ce99f6730cc8b2f3fda8b7f8d3522fc8127050d7f9e9785a12226ab91/swagger-conformance-0.2.2.tar.gz",
    "platform": "",
    "version": "0.2.2",
    "cheesecake_documentation_id": null,
    "description": "swagger-conformance\n===================\n\n|PyPI version| |Build Status| |codecov| |docs|\n\n|PyPI Versions| |PyPI License|\n\nYou have a Swagger (aka OpenAPI) schema defining an API you provide -\nbut does your API really conform to that schema, and does it correctly\nhandle all valid inputs?\n\n``swaggerconformance`` combines the power of ``hypothesis`` for property\nbased / fuzz testing with ``pyswagger`` to explore all corners of your\nAPI - testing its conformance to its specification.\n\nPurpose\n-------\n\nA Swagger/OpenAPI Spec allows you to carefully define what things are\nand aren't valid for your API to consume and produce. This tool takes\nthat definition, and tries to make requests exploring all parts of the\nAPI while strictly adhering to the schema. Its aim is to find any places\nwhere your application fails to adhere to its own spec, or even just\nfalls over entirely, so you can fix them up.\n\n*This is not a complete fuzz tester of your HTTP interface e.g. sending\ncomplete garbage, or to non-existent endpoints, etc. It's aiming to make\nsure that any valid client, using your API exactly as you specify, can't\nbreak it.*\n\nSetup\n-----\n\nEither install with ``pip install swagger-conformance``, or manually\nclone this repository and from inside it install dependencies with\n``pip install -r requirements.txt``.\n\nUsage\n-----\n\nAfter setup, the simplest test you can run against your API is just the\nfollowing from the command line:\n\n.. code:: bash\n\n    python -m swaggerconformance 'http://example.com/api/schema.json'\n\nwhere the URL should resolve to your swagger schema, or it can be a path\nto the file on disk.\n\nThis basic test tries all your API operations looking for errors. For\nexplanation of the results and running more thorough tests, including\nsequences of API calls and defining your custom data types, `see the\nexamples <https://github.com/olipratt/swagger-conformance/tree/master/examples>`__.\n\nDocumentation\n-------------\n\nFull documentation, including the example walkthroughs mentioned above\nand API documentation, is `available\nhere <https://pythonhosted.org/swagger-conformance/index.html>`__.\n\nWait, I don't get it, what does this thing do?\n----------------------------------------------\n\nIn short, it lets you generate example values for parameters to your\nSwagger API operations, make API requests using these values, and verify\nthe responses.\n\nFor example, take the standard `petstore\nAPI <http://petstore.swagger.io/>`__ example. At the time of writing,\nthat has an endpoint ``/pet`` with a ``PUT`` method operation that takes\na relatively complicated ``body`` parameter.\n\nWith just a little code, we can load in the swagger schema for that API,\naccess the operation we care about, and generate example parameters for\nthat operation:\n\n.. code:: python\n\n    >>> import swaggerconformance\n    >>>\n    >>> client = swaggerconformance.client.Client('http://petstore.swagger.io/v2/swagger.json')\n    >>>\n    >>> strategy_factory = swaggerconformance.strategies.StrategyFactory()\n    >>> operation = client.api.endpoints[\"/pet\"][\"put\"]\n    >>> strategy = operation.parameters_strategy(strategy_factory)\n    >>> strategy.example()\n    {\n      'body':{\n        'id':110339,\n        'name':'\\U00052ea5\\x9d\\ua79d\\x92\\x13\\U000f7c436!\\U000aa3c5R\\U0005b40e\\n',\n        'photoUrls':[\n          '\\ua9d9\\U0003fb3a\\x13\\U00025c1c\\U000974a8\\u3497\\U000515fa\\n',\n          \"\\U000b38a4>*\\u6683'\\U0002cd8f\\x0f\\n\"\n        ],\n        'status':'sold',\n        'category':{\n          'id':-22555826027447\n        },\n        'tags':[\n          {\n            'id':-172930,\n            'name':'\\U000286df\\u04dc\\U00033563\\u696d\\U00055ba8\\x89H'\n          }\n        ]\n      }\n    }\n    >>>\n\nSee `the\nexamples <https://github.com/olipratt/swagger-conformance/tree/master/examples>`__\nfor more details, and how to make requests against an API using these\nparameter values.\n\n.. |PyPI version| image:: https://badge.fury.io/py/swagger-conformance.svg\n   :target: https://badge.fury.io/py/swagger-conformance\n.. |Build Status| image:: https://travis-ci.org/olipratt/swagger-conformance.svg?branch=master\n   :target: https://travis-ci.org/olipratt/swagger-conformance\n.. |codecov| image:: https://codecov.io/gh/olipratt/swagger-conformance/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/olipratt/swagger-conformance\n.. |docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg\n   :target: https://pythonhosted.org/swagger-conformance/index.html\n.. |PyPI Versions| image:: https://img.shields.io/pypi/pyversions/swagger-conformance.svg\n   :target: https://pypi.python.org/pypi/swagger-conformance\n.. |PyPI License| image:: https://img.shields.io/pypi/l/swagger-conformance.svg\n   :target: https://pypi.python.org/pypi/swagger-conformance\n\n\n",
    "lcname": "swagger-conformance",
    "name": "swagger-conformance",
    "github": true,
    "coveralls": true,
    "bugtrack_url": null,
    "license": "MIT",
    "travis_ci": true,
    "github_project": "swagger-conformance",
    "summary": "Tool for testing whether your API conforms to its swagger specification",
    "split_keywords": [
        "swagger",
        "testing",
        "openapi",
        "hypothesis"
    ],
    "author_email": "olipratt@users.noreply.github.com",
    "urls": [
        {
            "has_sig": false,
            "upload_time": "2018-02-12T20:09:16",
            "comment_text": "",
            "python_version": "source",
            "url": "https://pypi.python.org/packages/5d/7b/cc1ce99f6730cc8b2f3fda8b7f8d3522fc8127050d7f9e9785a12226ab91/swagger-conformance-0.2.2.tar.gz",
            "md5_digest": "36882d802e605c22d1493ecfd6f7f404",
            "downloads": 0,
            "filename": "swagger-conformance-0.2.2.tar.gz",
            "packagetype": "sdist",
            "path": "5d/7b/cc1ce99f6730cc8b2f3fda8b7f8d3522fc8127050d7f9e9785a12226ab91/swagger-conformance-0.2.2.tar.gz",
            "size": 18177
        },
        {
            "has_sig": false,
            "upload_time": "2018-02-12T20:09:14",
            "comment_text": "",
            "python_version": "py3",
            "url": "https://pypi.python.org/packages/41/af/529c00bd4ba18eeb67d541c044532068ed19b63077a245462b918a105e1e/swagger_conformance-0.2.2-py3-none-any.whl",
            "md5_digest": "c274b2ce851e1e93a897e34e4323d3f8",
            "downloads": 0,
            "filename": "swagger_conformance-0.2.2-py3-none-any.whl",
            "packagetype": "bdist_wheel",
            "path": "41/af/529c00bd4ba18eeb67d541c044532068ed19b63077a245462b918a105e1e/swagger_conformance-0.2.2-py3-none-any.whl",
            "size": 54757
        }
    ],
    "cheesecake_installability_id": null
}
        
Elapsed time: 0.12034s