routeman vs the alternatives
There are several good ways to get a Postman collection for a Django, Flask, FastAPI, Express or NestJS API. Here's an honest look at when each one fits.
At a glance
| routeman | OpenAPI → Postman import | Hand-written | |
|---|---|---|---|
| Setup | pip install routeman or npx routeman-cli | Schema library + config + annotations (Django, Flask, Express, NestJS) | None |
| Source of truth | The app's real routes + serializers, DTOs, schemas, models and handler code | The generated schema | Whoever last edited it |
| Handlers without a serializer/schema | Fields read from handler 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.
swagger-jsdoc and swagger-autogen (Express)
Express has no schema of its own. swagger-jsdoc builds one from @openapi YAML blocks that you write in JSDoc comments above each route, and swagger-autogen guesses one by scanning the files. Either way, you then import the result into Postman. Hand-written YAML falls behind the code just like a hand-written collection does. routeman-cli reads the same routers, follows app.use() mounts, and takes bodies from your zod, Joi or express-validator schemas, or straight from req.body. If you already have a spec, npx routeman-cli --openapi spec.json still adds the login script, environments and smoke tests. See the Express guide.
@nestjs/swagger
@nestjs/swagger is the standard way to document a NestJS API, and its CLI plugin removes much of the decorator work. To get a Postman collection from it, you boot the app, download the JSON from the docs endpoint and import it. routeman-cli reads controllers, class-validator DTOs, mapped types and guards straight from the source, so it needs no running app, database or environment variables. It also reads @ApiProperty and @ApiOperation if you have them. See the NestJS guide.
express-list-endpoints and route printers
express-list-endpoints and similar helpers print the paths and methods of a running Express app. They're handy for a quick check, but they produce a list, not requests: no bodies, no auth and nothing Postman can import. They also need the app to start. npx routeman-cli routes gives you the same list, plus auth and body fields, without starting anything.
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, JavaScript or TypeScript, and you have no OpenAPI document either. With a spec,
routeman-cli --openapicovers any language. - Python edition: you can't import the application locally, for example because there's no virtualenv with its dependencies. (The Node.js edition doesn't need
node_modulesat all.) - Node.js edition: most of your routes are built at runtime from data, such as paths loaded from a database, so static analysis can't see them.
Questions about your setup? Contact us.