.. _openapi: .. currentmodule:: flask_smorest OpenAPI ======= `flask-smorest` 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`_, `Swagger UI`_ or `RapiDoc`_. API parameters -------------- The following API and OpenAPI parameters must be passed either as application configuration parameter or at initialization. If both are used, the application configuration parameter takes precedence. .. describe:: API_TITLE Title of the API. Human friendly string describing the API. API title must be passed either as application parameter or as `title` at :class:`Api ` initialization in ``spec_kwargs`` parameters. .. describe:: API_VERSION Version of the API. It is copied verbatim in the documentation. It should be a string, even if the version is a number. API version must be passed either as application parameter or as `version` at :class:`Api ` initialization in ``spec_kwargs`` parameters. .. describe:: OPENAPI_VERSION Version of the OpenAPI standard used to describe the API. It should be provided as a string. OpenAPI version must be passed either as application parameter or as `openapi_version` at :class:`Api ` initialization in ``spec_kwargs`` parameters. Add Documentation Information to Resources ------------------------------------------ Add Summary and Description ^^^^^^^^^^^^^^^^^^^^^^^^^^^ `flask-smorest` uses view functions docstrings to fill the `summary` and `description` attributes of an `operation object`. .. code-block:: python def get(pet_id): """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: .. code-block:: python { "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 :meth:`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 :meth:`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. A default error response is added automatically to the documentation of all resources. It is defined as a `response` component in the spec named ``"DEFAULT_ERROR"``. The name can be customized by setting ``Api.DEFAULT_ERROR_RESPONSE_NAME``. The feature can be opted out by setting it to ``None``. 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 :meth:`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. Likewise, path parameters in ``url_prefix`` are also automatically documented, and their automatic documentation can be completed by passing a ``parameters`` argument to the :meth:`Api.register_blueprint` method. Pass Extra Documentation Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `flask-smorest` 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 :meth:`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-smorest` is improved to fit the need. Known issues and alternatives are discussed in issue :issue:`71`. Populate the Root Document Object --------------------------------- Additional root document attributes can be passed either in the code, in :class:`Api ` parameter ``spec_kwargs``, or as Flask app configuration parameters. .. code-block:: python 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 .. code-block:: python {"host": "example.com", "x-internal-id": "2"} .. _document-top-level-components: Document Top-level Components ----------------------------- Documentation components can be passed by accessing the internal apispec :class:`Components ` object. .. code-block:: python api = Api(app) api.spec.components.parameter( "Pet name", "query", {"description": "Item ID", "required": True} ) .. _register-nested-blueprints: Register Nested Blueprints -------------------------- :class:`Blueprint ` objects can be nested just like standard `flask nested blueprints`_. Endpoints from nested blueprints are automatically documented, but only the top level blueprints generate new "tag" entries in the OpenAPI spec. The tag name and description are taken from the top level blueprints. Register Custom Fields ---------------------- Standard marshmallow :class:`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 :meth:`Api.register_field`: .. code-block:: python # 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 ('string, 'date-time') passing a marshmallow Field api.register_field(CustomDateTime, ma.fields.DateTime) 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 :meth:`Api.register_converter` allows to register a converter in the ``Api`` object to generate an accurate documentation. .. code-block:: python # Register MongoDB's ObjectId converter in Flask application app.url_map.converters["objectid"] = ObjectIdConverter # Define custom converter to schema function def objectidconverter2paramschema(converter): return {"type": "string", "format": "ObjectID"} # Register converter in Api api.register_converter(ObjectIdConverter, objectidconverter2paramschema) @blp.route("/pets/{objectid:pet_id}") def get_pet(pet_id): """Get pet by ID""" Enforce Order in OpenAPI Specification File ------------------------------------------- When a :class:`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: .. code-block:: python :emphasize-lines: 2,3 class MyBaseSchema(ma.Schema): class Meta: ordered = True class User(MyBaseSchema): name = ma.fields.String() surname = ma.fields.String() Serve the OpenAPI Documentation ------------------------------- Now that that the documentation is generated, it should be made available to the clients. `flask-smorest` 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. .. describe:: 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`` .. describe:: OPENAPI_JSON_PATH Path to the JSON file, relative to the base path. Default: ``openapi.json`` `ReDoc`_, `Swagger UI`_ and `RapiDoc` interfaces are available to present the API. Their configuration logics are similar. If an application path and a script URL are set, then `flask-smorest` adds a route at that path to serve the interface page using the JS script from the script URL. .. describe:: OPENAPI_REDOC_PATH Path to the ReDoc page, relative to the base path. Default: ``None`` .. describe:: OPENAPI_REDOC_URL URL to the ReDoc script. Examples: * https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js * https://rebilly.github.io/ReDoc/releases/v1.22.3/redoc.min.js * https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js * https://cdn.jsdelivr.net/npm/redoc@2.0.0-alpha.17/bundles/redoc.standalone.js * https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js Default: ``None`` .. describe:: OPENAPI_SWAGGER_UI_PATH Path to the Swagger UI page, relative to the base path. Default: ``None`` .. describe:: OPENAPI_SWAGGER_UI_URL URL to the Swagger UI script. Versions prior to 3.x are not supported. Examples: * https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/ * https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.25.0/ * https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.25.x/ * https://cdn.jsdelivr.net/npm/swagger-ui-dist/ Default: ``None`` .. describe:: OPENAPI_SWAGGER_UI_CONFIG Dictionary representing Swagger UI configuration options. See `Swagger UI Configuration`_ for available options. All JSON serializable options are supported. Examples: * ``{'deepLinking': True, 'supportedSubmitMethods': ['get', 'post']}`` Default: ``{}`` .. describe:: OPENAPI_RAPIDOC_PATH Path to the RapiDoc page, relative to the base path. Default: ``None`` .. describe:: OPENAPI_RAPIDOC_URL URL to the RapiDoc script. Examples: * https://unpkg.com/rapidoc/dist/rapidoc-min.js * https://cdn.jsdelivr.net/npm/rapidoc@9.0.0/dist/rapidoc-min.js * https://cdn.jsdelivr.net/npm/rapidoc/dist/rapidoc-min.js Default: ``None`` .. describe:: OPENAPI_RAPIDOC_CONFIG Dictionary representing RapiDoc configuration options. See `RapiDoc API`_ for available options. Examples: * ``{"theme": "dark"}`` Default: ``{}`` Here's an example application configuration using all available UIs: .. code-block:: python class Config: OPENAPI_VERSION = "3.0.2" OPENAPI_JSON_PATH = "api-spec.json" OPENAPI_URL_PREFIX = "/" OPENAPI_REDOC_PATH = "/redoc" OPENAPI_REDOC_URL = ( "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js" ) OPENAPI_SWAGGER_UI_PATH = "/swagger-ui" OPENAPI_SWAGGER_UI_URL = "https://cdn.jsdelivr.net/npm/swagger-ui-dist/" OPENAPI_RAPIDOC_PATH = "/rapidoc" OPENAPI_RAPIDOC_URL = "https://unpkg.com/rapidoc/dist/rapidoc-min.js" .. _ReDoc: https://github.com/Rebilly/ReDoc .. _Swagger UI: https://swagger.io/tools/swagger-ui/ .. _Swagger UI Configuration: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ .. _RapiDoc: https://mrin9.github.io/RapiDoc/ .. _RapiDoc API: https://mrin9.github.io/RapiDoc/api.html .. _flask nested blueprints: https://flask.palletsprojects.com/en/2.0.x/blueprints/#nesting-blueprints Write OpenAPI Documentation File -------------------------------- flask-smorest provides flask commands to print the OpenAPI JSON or YAML file to the standard output .. code-block:: none flask openapi print [--format=json|yaml] or write it to a JSON or YAML file .. code-block:: none flask openapi write [--format=json|yaml] openapi.json A typical use case is to write the OpenAPI documentation to a file in a deployment script to host it on a separate server rather than serving it from the application.