This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Swagger extension for Eve powered RESTful APIs.

Usage

from eve import Eve
from eve_swagger import swagger, add_documentation

app = Eve()
app.register_blueprint(swagger)

# required. See http://swagger.io/specification/#infoObject for details.
app.config['SWAGGER_INFO'] = {
    'title': 'My Supercool API',
    'version': '1.0',
    'description': 'an API description',
    'termsOfService': 'my terms of service',
    'contact': {
        'name': 'nicola',
        'url': 'http://nicolaiarocci.com'
    },
    'license': {
        'name': 'BSD',
        'url': 'https://github.com/nicolaiarocci/eve-swagger/blob/master/LICENSE',
    }
}

# optional. Will use flask.request.host if missing.
app.config['SWAGGER_HOST'] = 'myhost.com'

# optional. Add/Update elements in the documentation at run-time without deleting subtrees.
add_documentation({'paths': {'/status': {'get': {'parameters': [
    {
        'in': 'query',
        'name': 'foobar',
        'required': False,
        'description': 'special query parameter',
        'type': 'string'
    }]
}}}})

if __name__ == '__main__':
    app.run()

When the API is up and running, visit the /api-docs endpoint. The resulting JSON can then be used with swagger tooling, like the Swagger UI or Swagger Editor:

If you get the error “Can’t read from server. It may not have the appropriate access-control-origin settings” from Swagger UI, you might want to enable CORS support with the X_DOMAINS and X_HEADERS configuration in your Eve settings.py:

X_DOMAINS = ['http://localhost:8000',  # The domain where Swagger UI is running
             'http://editor.swagger.io',
             'http://petstore.swagger.io']
X_HEADERS = ['Content-Type', 'If-Match']  # Needed for the "Try it out" buttons

For more information check the CORS documentation of Swagger UI and Swagger Editor.

Installation

$ pip install eve-swagger

Description fields on the swagger docs

If you would like to include description fields to your swagger docs you can include a description field in your schema validations in your settings.py. This can be done per field as well as on the resource-level.

As an example:

...
'description': 'Description of the user resource',
'schema': {
    'userName': {
        'description': 'The username of the logged in user.',
        'type': 'string',
        'minlength': 1,
        'maxlength': 256,
        'required': True
    },
}
...

NOTE: If you do use that feature make sure that the TRANSPARENT_SCHEMA_RULES in your settings.py is also turned ON, otherwise you will get complains from the Cerberus library about “unknown field ‘description’ for field [yourFieldName]”

Disabling the documentation of a resource

You can disable the documentation of a specific resource by adding a disable_documentation field to the resource definition in settings.py. This means that the resource will not show up in the paths or definitions sections of the swagger docs.

...
'person': {
    'item_title': 'person',
    'disable_documentation': True,
    'schema': {...}
}
...

Enabling the documentation of Eve event hooks

By setting app.config['ENABLE_HOOK_DESCRIPTION'] to True you can enable the description of all Eve event hooks. This is done by showing the docstrings of the callback functions in the swagger docs under the appropriate paths.

def foo(request, lookup):
    """ Do something before GETting all the people """
    pass
def bar(response):
    """ Do something when you've fetched the database entries """
    pass
...
app.config['ENABLE_HOOK_DESCRIPTION'] = True
...
app.on_pre_GET_people += foo
app.on_fetched_resource_people += bar

The swagger docs will now look like this:

"paths": {
    "/people": {
        "get": {
            ...,
            "description": "**Hooks**:\n* `on_pre_GET_people`:\n\n  * `foo`:\n\n    Do something before GETting all the people\n\n\n* `on_fetched_resource_people`:\n\n  * `bar`:\n\n    Do something when you've fetched the database entries\n\n"
        }
    }
}

Which will be rendered by Swagger like this:

Release History

Release History

0.0.6

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
Eve-Swagger-0.0.6.tar.gz (13.7 kB) Copy SHA256 Checksum SHA256 Source Jan 3, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting