OpenAPI¶
flask-rest-api automatically generates an OpenAPI documentation (formerly known as Swagger) for the API.
That documentation can be made accessible as a JSON file, along with a nice web interface such as ReDoc or Swagger UI.
Specify Versions¶
The version of the API and the version of the OpenAPI specification can be specified as Flask application parameters:
-
API_VERSION
Version of the API. It is copied verbatim in the documentation. It should be a string, even it the version is a number.
Default:
'1'
-
OPENAPI_VERSION
Version of the OpenAPI standard used to describe the API. It should be provided as a string.
The OpenAPI version must be passed either as application parameter or at
Api
initialization inspec_kwargs
parameters.
Add Documentation Information to Resources¶
Add Summary and Description¶
flask-rest-api uses view functions docstrings to fill the summary and description attributes of an operation object.
def get(...):
"""Find pets by ID
Return pets based on ID.
---
Internal comment not meant to be exposed.
"""
The part of the docstring following the '---'
line is ignored.
The part before the '---'
line is used as summary and description. The
first lines are used as summary. If an empty line is met, all following lines
are used as description.
The example above produces the following documentation attributes:
{
'get': {
'summary': 'Find pets by ID',
'description': 'Return pets based on ID',
}
}
The delimiter line is the line starting with the delimiter string defined in
Blueprint.DOCSTRING_INFO_DELIMITER
. This string defaults to "---"
and
can be customized in a subclass. None
means “no delimiter”: the whole
docstring is included in the docs.
Document Operations Parameters and Responses¶
Schemas passed in Blueprint.arguments
to
deserialize arguments are parsed automatically to generate corresponding
documentation. Additional example
and examples
parameters can be used
to provide examples (those are only valid for OpenAPI v3).
Likewise, schemas passed in Blueprint.response
to
serialize responses are parsed automatically to generate corresponding
documentation. Additional example
and examples
parameters can be used
to provide examples (examples
is only valid for OpenAPI v3). Additional
headers
parameters can be used to document response headers.
Document Path Parameters¶
Path parameters are automatically documented. The type in the documentation is inferred from the path parameter converter used in the URL rule. Custom path parameters should be registered for their type to be correctly determined (see below).
The Blueprint.route
method takes a parameters
argument to pass documentation for parameters that are shared by all operations
of a path. It can be used to pass extra documentation, such as examples, for
path parameters.
Pass Extra Documentation Information¶
flask-rest-api tries to document the API as automatically as possible and to provide explicit means to pass extra-information that can’t be inferred from the code, such as descriptions, examples, etc.
The Blueprint.doc
decorator provides a means to pass
extra documentation information. It comes in handy if an OpenAPI feature is not
supported, but it suffers from a few limitations, and it should be considered
a last resort solution until flask-rest-api is improved to fit the need.
Known issues and alternatives are discussed in issue #71.
Populate the Root Document Object¶
Additional root document attributes can be passed either in the code, in
Api
parameter spec_kwargs
, or as Flask app configuration
parameters.
app.config['API_SPEC_OPTIONS'] = {'x-internal-id': '2'}
api = Api(app, spec_kwargs={'host': 'example.com', 'x-internal-id': '1'})
Note that app.config
overrides spec_kwargs
. The example above produces
{'host': 'example.com', 'x-internal-id': '2', ...}
Note
Again, flask-rest-api tries to provide as much information as possible, but some values can only by provided by the user.
When using OpenAPI v2, basePath is automatically set from the value of the flask parameter APPLICATION_ROOT. In OpenAPI v3, basePath is removed, and the servers attribute can only be set by the user.
Document Top-level Components¶
Documentation components can be passed by accessing the internal apispec
Components
object.
api = Api(app)
api.spec.components.parameter(
'Pet name',
'query',
{'description': 'Item ID', 'format': 'int32', 'required': True}
)
Register Custom Fields¶
Standard marshmallow Field
classes are
documented with the correct type and format.
When using custom fields, the type and format must be passed, either explicitly
or by specifying a parent field class, using Api.register_field()
:
# Map to ('string', 'ObjectId') passing type and format
api.register_field(ObjectId, 'string', 'ObjectId')
# Map to ('string') passing type
api.register_field(CustomString, 'string', None)
# Map to ('integer, 'int32') passing a code marshmallow field
api.register_field(CustomInteger, ma.fields.Integer)
Register Custom Path Parameter Converters¶
Likewise, standard types used as path parameter converters in the flask routes are correctly documented, but custom path converters must be registered.
The Api.register_converter()
allows to register a converter in the
Api
object to generate an accurate documentation.
# Register MongoDB's ObjectId converter in Flask application
app.url_map.converters['objectid'] = ObjectIdConverter
# Register converter in Api
api.register_converter(ObjectIdConverter, 'string', 'ObjectID')
@blp.route('/pets/{objectid:pet_id}')
...
Enforce Order in OpenAPI Specification File¶
When a Blueprint
is registered, a tag is created with
the Blueprint
name. The display order in the interface is the Blueprint
registration order. And the display order inside a tag is the order in which
the resources are defined in the Blueprint
.
In the OpenAPI specification file, the fields of a Schema
are documented as
schema properties. Although objects are not ordered in JSON, OpenAPI
graphical interfaces tend to respect the order in which the properties are
defined in the properties
object in the specification file.
When using an ordererd Schema
, the fields definition order is preserved
when generating the specification file and the properties are displayed in
that order.
This is typically done in a base class:
class MyBaseSchema(ma.Schema):
class Meta:
ordered = True
class User(MyBaseSchema):
name = ma.fields.String()
surname = ma.fields.String()
Passing ordered
Meta attribute is not necessary when using a Python version
for which dictionaries are always ordered (>= 3.7 or CPython 3.6).
Serve the OpenAPI Documentation¶
Now that that the documentation is generated, it should be made available to the clients. flask-rest-api can define routes to provide both the documentation as a JSON file and a nice web interface to browse it interactively. This feature is accessible through Flask app parameters.
-
OPENAPI_URL_PREFIX
Defines the base path for both the JSON file and the UI. If
None
, the documentation is not served and the following parameters are ignored.Default:
None
-
OPENAPI_JSON_PATH
Path to the JSON file, relative to the base path.
Default:
openapi.json
Both ReDoc and Swagger UI interfaces are available to present the API.
Their configuration logics are similar. If a path is set, then flask-rest-api creates a route in the application to serve the interface page, using the JS script from a user defined URL, if any, or from a CDN URL built with the version number.
-
OPENAPI_REDOC_PATH
If not
None
, path to the ReDoc page, relative to the base path.Default:
None
-
OPENAPI_REDOC_URL
URL to the ReDoc script. If
None
, a CDN version is used.Default:
None
-
OPENAPI_REDOC_VERSION
ReDoc version as string. Should be an existing version number,
latest
(latest 1.x version) ornext
(latest 2.x version).This is used to build the CDN URL if
OPENAPI_REDOC_URL
isNone
.On a production instance, it is recommended to specify a fixed version number.
Default:
'latest'
-
OPENAPI_SWAGGER_UI_PATH
If not
None
, path to the Swagger UI page, relative to the base path.Default:
None
-
OPENAPI_SWAGGER_UI_URL
URL to the Swagger UI script. If
None
, a CDN version is used.Default:
None
-
OPENAPI_SWAGGER_UI_VERSION
Swagger UI version as string. Contrary to ReDoc, there is no default value pointing to the latest version, so it must be specified.
This is used to build the CDN URL if
OPENAPI_SWAGGER_UI_URL
isNone
.Default:
None
-
OPENAPI_SWAGGER_UI_SUPPORTED_SUBMIT_METHODS
List of methods for which the ‘Try it out!’ feature is enabled. Should be a list of lowercase HTTP methods.
Passing an empty list disables the feature globally.
Default:
['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']
Warning
The version strings are not checked by flask-rest-api. They are used as is to build the URL pointing to the UI script. Typos won’t be caught.