Flask apispec tools

A set of tools to aid in adding APISpec to Flask projects.

pip install flask-apispec-tools

flask-apispec-tools requires the following inside the Flask app config.

[FLASK_APISPEC_TOOLS]
version =
title =
description =
docs_dir =
docs_type =

There are multiple ways to add the config items to the Flask app. See Flask Configuration Handling. While it is recommended to use separate config files or environment variables, flask-apispec-tools allows you to pass configuration values to the init() function. See Configuring flask-apispec-tools with init().

Config values can be references to other config options using the format ${section:option}.

[FLASK_APISPEC_TOOLS]
version = ${METADATA:version}
title = ${METADATA:title}
description = ${METADATA:description}
docs_dir = myproj/static/docs
docs_type = json

flask_apispec_tools.init(app)

This registers the cli command generate-api-docs with Flask and adds 3 endpoints ( /docs, /docs/json or /docs/yaml, /version) to the app.

Adding these endpoints can be disabled or their paths can be changed by passing additional arguments to init().

The example below sets the paths for the docs and docs_json endpoints and disables the version endpoint.

flask_apispec_tools.init(
    app,
    docs_endpoint='/api/docs',
    docs_json_endpoint='/api/docs/json',
    version_endpoint=False
)

A list of apispec plugins can be passed to init() and they will be given to the APISpec object. See APISpec Using Plugins. You do not need to give init() the FlaskPlugin.

flask_apispec_tools.init(
    app,
    plugins=[MarshmallowPlugin(), MyCustomPlugin()]
)

flask-apispec-tools can be configured by passing a dictionary of config values to init(). This will override any existing configuration values.

flask_apispec_tools.init(
    app,
    config_values={
        'docs_dir': '/docs',
        'docs_type': 'json'
    }
)

flask generate-api-docs

-a, --all Include enpoints marked 'Exclude From Spec'.

Endpoints can be excluded from docs by adding Exclude From Spec at the top of the docstring. This exclusion can be ignored using -a or --all with flask generate-api-docs.

class MyEndpoint(MethodView):
    """Exclude From Spec"""

    def get(self):
        ...

flask-apispec-tools provides a function that you can register with a Flask Test Client to run after each request sent during tests. The validator inspects both the Request and Response objects and compares them to the API specification. If the validation fails an APISpecError is raised, and the test will fail.

from flask_apispec_tools.testing import response_validator

   ...
   app.after_request(response_validator())
   ...

==================================== short test summary info ====================================
FAILED tests.py::test_docs - apispec.exceptions.APISpecError: GET /docs -> 200: text/html missing
================================== 1 failed, 41 passed in 0.49s =================================

These functions are used internally, but you may find them useful as well.

Get the value of an option from the config.

Args:
	option: The option to get the value for.
	config: Optional. Default: flask.current_app.config.
Returns:
	str: The config value.
	None: The option was not found.

Get the name of a docs file for a specific version.

Args:
	version: Optional. Default: The version set in the config.
	config: Optional. Default: flask.current_app.config.
Returns:
	 The docs filename.

Get the filepath of a docs file for a specific version.

Args:
	version: Optional. Default: The version set in the config.
	config: Optional. Default: flask.current_app.config.
Returns:
	The docs filepath.