Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Swagger extension for Eve powered RESTful APIs

Project description

Build status Python versions

Swagger extension for Eve powered RESTful APIs.


from eve import Eve
from eve_swagger import swagger, add_documentation

app = Eve()

# required. See 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': ''
    'license': {
        'name': 'BSD',
        'url': '',
    'schemes': ['http', 'https'],

# optional. Will use if missing.
app.config['SWAGGER_HOST'] = ''

# 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__':

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

X_DOMAINS = ['http://localhost:8000',  # The domain where Swagger UI is running
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.


$ 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 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 is also turned ON, otherwise you will get complains from the Cerberus library about “unknown field ‘description’ for field [yourFieldName]”, or use a custom schema validator, as below:

from import Validator

class MyValidator(Validator):
    def _validate_description(self, description, field, value):
        """ {'type': 'string'} """
        # Accept description attribute, used for swagger doc generation

app = Eve(validator=MyValidator)

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 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 """
def bar(response):
    """ Do something when you've fetched the database entries """
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:


Example fields on the docs

Like a description, an example can be added to a field.

'schema': {
    'lastName': {
        'example': 'Doe',
        'type': 'string',
        'minlength': 1,

The example is shown in the swagger ui in the model and the responses.


NOTE: As with the description, the field TRANSPARENT_SCHEMA_RULES must be enabled in your, otherwise the Cerberus library will display an error about “unknown field ‘example’ for field[yourFieldName]”.

If you do not want to use this rule for the entire schema, you can also use your own validator.

from import Validator

class MyValidator(Validator):
    def _validate_example(self, example, field, value):
        if example and not isinstance(value, str):
            self._error(field, "Value must be a string")


app = Eve(validator=MyValidator)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Eve-Swagger, version 0.0.11
Filename, size File type Python version Upload date Hashes
Filename, size Eve-Swagger-0.0.11.tar.gz (17.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page