API Docs with OpenAPI & Swagger
OpenAPI is a standard, machine-readable way to describe a REST API — every path, parameter, request body, and response — so that both humans and tools understand exactly how your API behaves.
Learn API Docs with OpenAPI & Swagger in our free Flask course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick…
Part of the free Flask course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
In this lesson you'll document a Flask API with flask-smorest , define marshmallow schemas, validate input with @blp.arguments , serialize output with @blp.response , and get an interactive Swagger UI for free.
OpenAPI is a standard format — usually written as JSON or YAML — that describes a REST API in a way machines can read. It lists every path, the parameters each one accepts, the shape of request bodies, and the responses they return. It used to be called Swagger , and that name still appears in tools like Swagger UI .
Why bother? Because one document becomes a single source of truth. From it, tools can auto-generate client libraries, mock servers, contract tests, and interactive docs. Hand-written documentation drifts out of date; a generated spec stays accurate.
flask-smorest is an extension that builds REST APIs and documents them at the same time. You define marshmallow schemas for your data, register routes on a special Blueprint with @blp.route , and decorate them with @blp.arguments (to validate input) and @blp.response (to serialize output). flask-smorest reads all of this and produces the OpenAPI document for you.
Once your app runs, flask-smorest serves an interactive documentation page at the path you configured — here /swagger-ui . Open it in a browser and you'll see every endpoint, its parameters, the schemas, and a "Try it out" button that sends real requests to your running API. The raw machine-readable OpenAPI JSON is available at its own URL so other tools can consume it.
A second popular option is flasgger , which builds Swagger UI from docstrings and YAML (often via the apispec library). It is handy for adding docs to an existing app without restructuring it around schemas.
Complete the documented route below. Replace each ___ so it validates the body and serializes the response.
The request body failed schema validation. flask-smorest returns this automatically when a required field is missing or has the wrong type — check the JSON you sent against your schema.
Make sure OPENAPI_VERSION and the Swagger UI config keys are set, and that you visit the configured path such as /swagger-ui .
Add a route that fetches one item by its id and documents the response.
Lesson 22 complete — your API documents itself!
You can describe an API with the OpenAPI standard, build documented endpoints with flask-smorest and marshmallow schemas, and serve an interactive Swagger UI. Your docs now stay in lockstep with your code.
🚀 Up next: DB Transactions & Query Optimization — make your database work atomic and fast.
Practice quiz
What is OpenAPI?
- A standard format for describing REST APIs
- A database driver
- A testing framework
- A Flask extension only
Answer: A standard format for describing REST APIs. OpenAPI is a language-agnostic standard for describing REST APIs in a machine-readable document.
What was OpenAPI formerly called?
- RAML
- API Blueprint
- Swagger
- WSDL
Answer: Swagger. The OpenAPI Specification grew out of the Swagger spec, and the Swagger name still lives on in tools like Swagger UI.
Which Flask extension builds APIs with auto-generated OpenAPI docs using marshmallow?
- flask-cors
- flask-smorest
- flask-login
- flask-migrate
Answer: flask-smorest. flask-smorest pairs Flask with marshmallow schemas and produces an OpenAPI document plus Swagger UI automatically.
In flask-smorest, what do you use instead of Flask's plain Blueprint?
- app.route
- a class-based view
- render_template
- flask_smorest.Blueprint
Answer: flask_smorest.Blueprint. flask-smorest provides its own Blueprint class that records route and schema metadata for the docs.
Which decorator declares the request body schema in flask-smorest?
- @blp.arguments
- @blp.payload
- @blp.body
- @blp.input
Answer: @blp.arguments. @blp.arguments(SomeSchema) validates and deserializes the incoming request using a marshmallow schema.
Which decorator declares the response schema and status code?
- @blp.send
- @blp.response
- @blp.returns
- @blp.output
Answer: @blp.response. @blp.response(200, SomeSchema) serializes the return value and documents the response shape.
What library defines the schemas flask-smorest validates against?
- pydantic
- cerberus
- voluptuous
- marshmallow
Answer: marshmallow. flask-smorest uses marshmallow Schema classes to validate input and serialize output.
What interactive documentation page does flask-smorest generate by default?
- A plain text file
- A GraphQL playground
- Swagger UI
- A Postman collection
Answer: Swagger UI. flask-smorest serves Swagger UI (and ReDoc) so users can read and try the API in the browser.
Why do machine-readable API docs matter?
- They encrypt requests
- Tools can generate clients, tests, and docs from one source of truth
- They make code run faster
- They replace the need for a database
Answer: Tools can generate clients, tests, and docs from one source of truth. A standard spec lets tools auto-generate client SDKs, mock servers, and tests, keeping everything in sync.
Which other extension generates Swagger docs from docstrings and YAML?
- flasgger
- flask-wtf
- flask-caching
- flask-sqlalchemy
Answer: flasgger. flasgger reads docstrings and YAML (often via apispec) to build a Swagger UI for an existing Flask app.