OpenAPI & API Documentation

Flask validates nothing and documents nothing by itself: a view receives a request and returns whatever it likes (see Request Data and Responses & JSON). That freedom is exactly why an API needs a contract. The OpenAPI Specification (OAS) is a language-neutral way of writing that contract as a JSON or YAML document: the paths, the operations on each path, the parameters, the request bodies, the responses, the data types and the security requirements. Because it is machine-readable, the same document feeds many tools.

The API-first idea, argued at length in Microservice APIs (Manning), is that the interface between services is the part that is expensive to change, so it deserves a document that is reviewed, versioned and agreed before the implementation. Whether the document is written first or generated, the rule stays the same: the running service and the published document must never disagree.

There are two workflows, and Flask libraries exist for both.

The rest of the page follows the code-first path with flask-smorest first, because it is the most complete option for plain Flask, then APIFlask, then the design-first path with a validated hand-written document. Both are only as good as the checks around them, which is why the page ends with contract validation.

An OpenAPI document is a single JSON or YAML object. The OpenAPI Specification 3.1 is aligned with JSON Schema draft 2020-12, so the objects that describe data (schema) are ordinary JSON Schema, with a few OpenAPI keywords added.

A document needs openapi and info, and at least one of paths, components or webhooks. Inside paths, each operation lists its parameters (each with a name, a location in in, either path, query, header or cookie, and a schema), an optional requestBody keyed by media type, and responses keyed by status code (or default). Every response has a mandatory description and optionally content and headers. The reusable parts live in components and are referenced with $ref, so that the same Book schema is written once and used by the request of POST /books and the response of GET /books/{bookId}. Security is declared once under components.securitySchemes (types apiKey, http, oauth2, openIdConnect and mutualTLS) and applied with security, which is how Swagger UI knows to show an "Authorize" button.

Source: OpenAPI Specification v3.1.1

Flask-RESTful with reqparse, used by Flask Framework Cookbook (Packt), is maintained at a minimal level and has no OpenAPI support; use one of the libraries above for new work. A fuller comparison with maintenance status belongs to the page on building REST APIs in this section.

Source: flask-smorest documentation

flask-smorest (installed with pip install flask-smorest) combines three libraries: marshmallow describes the data, webargs parses requests into those schemas, and apispec builds the OpenAPI document from everything it sees. The Flask part is deliberately small: an Api object attached to the application, a Blueprint subclass whose decorators carry the documentation, and the standard Flask MethodView from Class-Based Views to group the methods of a resource.

A marshmallow Schema does three jobs at once: it validates and deserializes input (load), it serializes output (dump), and, through apispec, it becomes an entry under components.schemas of the document. The vocabulary that matters for an API is small.

@blp.arguments(schema, location="json") is not limited to bodies. The location argument chooses where webargs looks for the data: json (the default), query, form, files, headers, cookies, among others webargs supports. For json, form and files the schema becomes the requestBody and required and description apply to it; for the other locations each field of the schema becomes one entry of parameters with its own required flag, and the required argument of the decorator has no effect. That is the part worth remembering when a query parameter looks optional in the document although you passed required=True.

Query schemas usually want unknown = EXCLUDE, because browsers, proxies and trackers add parameters (utm_source, _ cache busters) that you do not want to turn into a 422.

Source: flask-smorest: Arguments

@blp.response(status_code, schema) describes the success response. A few points about it are easy to miss.

Errors have a default format. abort(status, message=..., errors=..., headers=...) is a republication of webargs' abort that stores its keyword arguments so the registered handler can render them as {"code": ..., "status": ..., "message": ..., "errors": ...}. Validation failures raised by @blp.arguments are the same kind of HTTPException, with the field errors under errors keyed by location. The default answer is documented once as components.schemas.Error and used for every operation as the default response, plus a 422 response for operations with @blp.arguments.

Source: flask-smorest: Response

The last two lines show a pitfall: marshmallow’s ValidationError raised inside a view is not an HTTPException, so it is not converted to a 422; Flask turns it into a plain 500 (see Error Handling for how the handlers are chosen). Validation belongs in @blp.arguments; to fail from the middle of a view use abort(422, ...) or abort(409, ...), or register your own handler for the exception.

@blp.paginate() adds page and page_size to the query parameters and the metadata to the response in an X-Pagination header (total, total_pages, page, first_page, last_page, and previous_page and next_page when they exist). It has two modes. In the first the view receives a pagination_parameters object, slices its own data and sets item_count. In the second paginate receives a pager class (a subclass of flask_smorest.Page, such as one wrapping a SQLAlchemy query) and the view just returns the whole collection or a lazy cursor.

They can be changed globally in Blueprint.DEFAULT_PAGINATION_PARAMETERS or per endpoint as arguments of @blp.paginate(page=..., page_size=..., max_page_size=...); the header name is Blueprint.PAGINATION_HEADER_NAME (None disables the header). A request for a larger page_size than allowed is rejected by the generated parameter schema (maximum: 100), which protects the database from page_size=1000000.

Source: flask-smorest: Pagination

The related ETag support (@blp.etag, conditional If-None-Match and If-Match requests for caching and optimistic locking) is described in the flask-smorest documentation and adds its own documented headers; the page on building REST APIs in this section covers when to use pagination styles and conditional requests.

The decorators produce structure; people read the prose. Four sources add it.

Security deserves its own mention. The document is where an operation says "this requires a bearer token", but flask-smorest only describes security, it does not enforce it: the view or a decorator from Hooks & View Decorators still has to authenticate the request, as shown in Authorization & Roles. A securitySchemes entry plus a security requirement makes Swagger UI and generated clients send the credential. The page on JWT and API authentication in this section builds the matching implementation.

Source: flask-smorest: OpenAPI, Adding documentation

When OPENAPI_URL_PREFIX is set, flask-smorest registers an extra blueprint that serves the document at <prefix>/openapi.json (or OPENAPI_JSON_PATH) and, for each UI whose path and script URL are both set, an HTML page that loads the UI from that URL. The three supported UIs are Swagger UI, ReDoc and RapiDoc; none is bundled, they are pulled from a CDN or from a location you host.

Source: flask-smorest: OpenAPI, Serving the OpenAPI documentation

Publishing documentation raises operational questions that a decorator cannot answer.

Api registers a Click group named openapi (see the page on the Flask CLI). flask --app bookshelf openapi print writes the document to standard output and flask --app bookshelf openapi write openapi.json writes it to a file; both accept --format json|yaml (YAML needs PyYAML installed) and --config-prefix for applications with several Api objects; openapi list-config-prefixes shows the prefixes.

Committing the generated file and failing the build when git diff is not empty turns every API change into a visible diff in the pull request, which is how code-first projects get the review step that design-first projects get from writing the document by hand. The same generated file is the input to linters, generators and contract tests, so no server has to be running.

Source: flask-smorest: OpenAPI, Print or write the OpenAPI file

APIFlask (pip install apiflask) takes a different shape. APIFlask subclasses Flask, so plain Flask views keep working, and it adds decorators on the application and its blueprints (APIBlueprint) instead of on a separate Blueprint class. It documents and serves the OpenAPI document and a UI out of the box with no extra configuration, and it accepts marshmallow schemas.

Source: APIFlask: OpenAPI Generating

In the command line, flask --app bookshelf spec --format yaml --output openapi.yaml produces the same kind of file as the flask-smorest command. The flask spec command is installed as a Flask plugin command (a flask.commands entry point), so it appears in the real flask executable but not in app.test_cli_runner(). APIFlask’s @app.spec_processor hook lets you rewrite the finished document, and @app.doc(hide=True) or APIFlask(__name__, enable_openapi=False) removes operations or the whole feature.

Source: APIFlask: API Documentations

In design-first the document is the product of a design conversation. The team writes the YAML (an editor with an OpenAPI plug-in, or a design tool), reviews it, publishes it to front-end and partner teams, and only then implements. The risk is drift, so the workflow needs automation at three points: the document must be valid, the application must serve or reference it, and the implementation must be checked against it.

Validate the document. openapi-spec-validator (pip install openapi-spec-validator) checks a document against the specification schema for the version it declares, including $ref resolution, and raises on the first problem.

Serve it. Nothing in Flask requires a framework: a view that returns the parsed document is enough, and any of the UIs from the previous section can be pointed at it. With flask-smorest, set OPENAPI_URL_PREFIX to None (so the generated document is not published) and serve your file from your own route. The book Microservice APIs replaces the served document by monkeypatching APISpec.to_dict; that works only as a workaround, because it ties the application to a private detail of the library and defeats the point of the generator. If you want the spec to drive the application rather than sit beside it, Connexion maps each operationId to a Python function and validates requests and responses against the document at run time.

Check the implementation. The simplest contract test needs only jsonschema: for every operation, call the endpoint with the Flask test client and validate the response body against the schema the document declares for that status code. Components are referenced as #/components/schemas/..., so the validator is given a root object that carries both the schema and components. Dedicated tools do the same at scale: Schemathesis generates the requests from the document and fuzzes the API, and openapi-core validates requests and responses with Flask integration (both discussed in the page on API contract and property-based testing in this section; Dredd, used in the book, is archived).

Source: openapi-spec-validator

Because the document is the contract, consumers can generate their side of it. Quality in equals quality out: give every operation a stable operationId (flask-smorest does not invent one, so set it with @blp.doc(operationId=...); APIFlask has the AUTO_OPERATION_ID setting) because generators use it as the method name, and give every schema a meaningful name because they use it as the class name.

Review generated clients like any dependency: regenerate them in CI from the committed document so that a breaking API change fails somewhere visible, and treat the generated code as build output, not as hand-edited source.

Source: openapi-python-client

The Manning book Microservice APIs (José Haro Peralta, 2022/2023) is a good guide to API design, and chapter 5 gives the anatomy of an OpenAPI document; for flask-smorest, its chapter 6 contains errors and outdated choices that this page corrects. The Packt Flask Framework Cookbook editions and Full-Stack Flask and React document APIs with Flask-RESTful or Postman collections instead of OpenAPI. In summary: