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

routemanOpenAPI → Postman importHand-written
Setuppip install routeman or npx routeman-cliSchema library + config + annotations (Django, Flask, Express, NestJS)None
Source of truthThe app's real routes + serializers, DTOs, schemas, models and handler codeThe generated schemaWhoever last edited it
Handlers without a serializer/schemaFields read from handler codeUsually empty bodiesTyped by hand
Example values that validateYes (choices, ranges, lengths, patterns, field names)Depends on schema examplesBy hand
Login request stores tokenYesNoScript by hand
EnvironmentsOne per serverPartly, from serversBy hand
Smoke tests5xx check on every requestNoBy hand
Interactive docs (Swagger UI / Redoc)No, it's not a docs serverYesNo
Client SDK generationNoYes (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 --openapi covers 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_modules at 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.