routeman vs the alternatives
There are several good ways to get a Postman collection for a Django, Flask or FastAPI API. Here's an honest look at when each one fits.
At a glance
| routeman | OpenAPI → Postman import | Hand-written | |
|---|---|---|---|
| Setup | pip install routeman | Schema library + config + annotations (Django/Flask) | None |
| Source of truth | The running app's routes + serializers/forms/models/view code | The generated schema | Whoever last edited it |
| Views without a serializer/schema | Fields read from view code | Usually empty bodies | Typed by hand |
| Example values that validate | Yes (choices, ranges, lengths, patterns, field names) | Depends on schema examples | By hand |
| Login request stores token | Yes | No | Script by hand |
| Environments | One per server | Partly, from servers | By hand |
| Smoke tests | 5xx check on every request | No | By hand |
| Interactive docs (Swagger UI / Redoc) | No, it's not a docs server | Yes | No |
| Client SDK generation | No | Yes (via OpenAPI generators) | No |
OpenAPI / Swagger import
Postman can import an OpenAPI 3 document and turn it into a collection. If your project already has an accurate, well-annotated schema, that's a reasonable path, and the schema also gives you Swagger UI and SDK generation.
The gaps show up in Postman itself. The imported collection doesn't know which request logs in, so you write the token script yourself. Environments are limited to the schema's servers. Request bodies are only as good as the schema, and views the generator couldn't understand come through empty. Every update means exporting and re-importing again.
Use both: routeman doesn't replace your OpenAPI docs. Many teams keep Swagger UI for public documentation and use routeman for the Postman collection the team works in every day.
drf-spectacular and drf-yasg
These are excellent OpenAPI generators for Django REST framework. They need configuration, and often @extend_schema/@swagger_auto_schema annotations on views they can't introspect, such as APIViews that build serializers by hand or views reading request.data directly. routeman reads the same serializers and also handles those views without annotations. It doesn't work with plain Django views, though, and plain Django views are where routeman is most useful.
flasgger, apispec and flask-smorest
Flask has no built-in schema, so these libraries ask you to describe each endpoint in YAML docstrings, marshmallow schemas or decorators. If you already use flask-smorest or marshmallow, routeman reads those schemas. If you don't, routeman reads request.json, request.form and request.args usage in your view code, so you get a useful collection without adopting a documentation library.
FastAPI's /openapi.json
FastAPI generates OpenAPI for free, so importing /openapi.json is easy. routeman uses the same document (built in memory, without a running server) and adds the Postman parts the import lacks: the OAuth2/JWT login script, collection-level auth with public routes set to No Auth, environments, smoke tests, and routes hidden with include_in_schema=False. See the FastAPI guide.
Postman's own tools
Postman can capture requests through its proxy or interceptor, and it can sync collections from API definitions. Those tools are useful for recording real traffic, but each request has to be exercised first. routeman works from the code, so endpoints nobody has called yet are included too.
Hand-written collections
Hand-written collections give you full control, but they drift from the code the moment someone adds a field. A good compromise is to generate with routeman, then keep your hand-written tests in a separate collection or folder. Because routeman's ids are stable, re-importing updates the generated part in place.
When routeman is not the right tool
- You need a public, interactive API reference. Use an OpenAPI tool (and routeman alongside it, if you like).
- Your API isn't written in Python, or uses a framework other than Django, DRF, Flask or FastAPI.
- You can't import the application locally, for example because there's no virtualenv with its dependencies.
Questions about your setup? Contact us.