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.

What You'll Learn in This Lesson

1 The OpenAPI / Swagger Standard

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.

2 Building an API with flask-smorest

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.

3 The /swagger-ui Endpoint

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.

🎯 Your Turn: Fill in the Blanks

Complete the documented route below. Replace each ___ so it validates the body and serializes the response.

Common Errors & Quick Reference

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 .

Task

Code

Install tools

pip install flask-smorest marshmallow

Define a schema

class PetSchema(Schema): ...

Validate input

@blp.arguments(PetSchema)

Serialize output

@blp.response(200, PetSchema)

View docs

/swagger-ui

🏆 Mini Challenge: Document a GET-by-id Route

Add a route that fetches one item by its id and documents the response.

• Add a route with an <int:pet_id> path parameter
• Decorate it with @blp.response(200, PetSchema)
• Return a single object matching the schema

❓ Frequently Asked Questions

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

Continue this course

• Previous: Capstone: A Full CRUD App
• Next: DB Transactions & Query Optimization