Two APIs/routes from one app?

[lpw]

I'm trying to serve two related APIs (distinguished by two distinct top-level prefixes in their routes), generating two separate swagger docs with respective endpoints via swaggerUi.serveFiles, from one express-zod-api app.

Can multiple routes (which then requires multiple configs for different tags) be used in one express-zod-api app?

Normally the server and port are specified to createConfig, the resulting config used to create tagged endpoints, which are used to form routes, then those config and routes are passed to createServer.

If multiple configs and routes are created, instead of calling createServer which takes only one set of config and routes, I could create app = express(). Or perhaps {app} = await createServer on one of the config/route sets, or an empty config/route. Then use attachRouting for the remaining or each of the configs and routes.

Unfortunately, that doesn't seem to work because attachRouting apparently doesn't parse request.body for the input to the handlers, failing input validation based to zod types. I see the note in Connect to your own express app about "you probably need to parse request.body". Perhaps that requires middleware, but was hoping not to increase the complexity by adding this addition route set.

Even if I disabled by validation by using an empty z.object({}), it's not clear how to access the request from the endpoint handler function args.

Is there any way to serve two routes using besides using attachRouting? If attachRouting is my only option, what's the best way to at least get the body input (even if not validated) to the handler function?

Thanks for any ideas or thoughts or alternative on this - really liking express-zod-api!

[RobinTail]

Hello, @lpw

I'm trying to serve two related APIs (distinguished by two distinct top-level prefixes in their routes),

Could you please clarify: are those APIs listening to the same port?
What is the nature of those prefixes? Is it a version like v1 and v2?

Can multiple routes (which then requires multiple configs for different tags) be used in one express-zod-api app?

Could you please clarify the differences of those two configs?
Do they only have different tags?

If the only difference is tags, I could suggest to:

• create const tagsV1 = {}, tagsV2 = {}, tags = {...tagsV1, ...tagsV2};
• create routingV1, routingV2, routing in a similar way;
• run a single createServer() with routing and single config having tags;
• in endpoints additionally use tag: "" satisfies keyof typeof tagsV1 (you can make a shorter type for that);
• supply routingV1 or routingV2 to Documentation individually,
  • and {...config, tags: tagsV1} for listing only the tags belonging to the certain version (overridden tags only for the documentation).

attachRouting apparently doesn't parse request.body

Yes, it does not. It's intended for the DIY solutions.

[lpw]

Hi Robin (or Anna)!

Thanks for the fast reply.

Your presumptions are correct, listening to the same port, with different tags and routes. The original API is splitting into two, so they are somewhat related, still sharing much of the same backend code, which is why it'd be nice to leave it as one service, and even more conveniently on one port.

Following your suggestions, I split the tags and routes for doc gen, then spread and combined the tags and routes to createServer - that works!

The only problem is that the app returned from createServer doesn't serve docs correctly (status: "error", message: "Can not GET /docs/v1/"). I'm not sure what is different about createServer's app that'd inhibit the doc route. I'm not sure why the following two approaches yield such different results.

const v1DocFilePromise = writeFile(
  './v1.documentation.json',
  new Documentation({
    routing: v1Routing,
    config: v1Config,
    serverUrl: [ `${host}` ],
  }).getSpecAsJson(),
  'utf-8',
)
const config = createConfig({ server: { listen: port }, tags: combinedTags })
createServer( config, combinedRouting ).then( ({ app }) => {
  v1DocFilePromise.then( () => {
    const swaggerFile = require( 'v1.documentation.json' )
    app.use('/docs/v1', swaggerUi.serveFiles( swaggerFile, {} ), swaggerUi.setup( swaggerFile ))
  })
})

Serving the docs works correctly when using an app direct from express and using attachRouting instead of createServer:

const app = express()
const config = createConfig({ app, tags: combinedTags })
v1DocFilePromise.then( () => {
  const swaggerFile = require( 'v1.documentation.json' )
  app.use('/docs/v1', swaggerUi.serveFiles( swaggerFile, {} ), swaggerUi.setup( swaggerFile ))
})
attachRouting( config, combinedRouting )
app.listen( port )

but the problem with attachRouting is the lack of request body parsing, as you've mentioned and confirmed (I swear attachRouting used to work, parsing the body and passing to input of the handler, but that was back on express-zod-api 8.11).

I welcome any further advice.

Thanks for all your work on express-zod-api.

-Lance.

[RobinTail]

Following your suggestions, I split the tags and routes for doc gen, then spread and combined the tags and routes to createServer - that works!

That's a great news, @lpw

Serving the docs works correctly when using an app direct from express and using attachRouting instead of createServer

That's because besides the API you're hosting the UI, establishing its own API via app.use.
In case of createServer, that .use() goes after the "not found handler" being already in place.
So that's why it only works with attachRouting() currently.

lack of request body parsing

By the way, enabling the body parsing (the JSON in particular) is very easy:

const app = express();
app.use(express.json());

I welcome any further advice.

Well, I see two possible ways here:

• for the server, which is serving the UI — use the attachRouting() approach;
• otherwise, I have an idea on enabling a list of express middlewares to run BEFORE the actual API's routing — that will enable you to keep createServer approach while moving the following line into config:

app.use('/docs/v1', swaggerUi.serveFiles( swaggerFile, {} ), swaggerUi.setup( swaggerFile ))

I'll make a PR to show what I mean.

[RobinTail]

Check this out, @lpw :

#1549

Would you be interested in helping me to test this feature?

[RobinTail]

I managed to set that Swagger UI thing up for the demonstration purposes and it seems to be working fine with createServer() by utilizing the proposed feature, @lpw :

[RobinTail]

Dear @lpw ,

🚀 I published a dev preview version 16.7.0-beta1 having server.beforeRouting option in config.
Could you please try it in a similar way I explained in the Changelog and let me know if your Swagger UI is now working correctly even when using createServer() method?

[lpw]

Just pulled v16.7.0-beta1 and tested - works great! Nicely designed, keeping it in the server spec of createConfig. I'll keep testing, let me know how else I can help. Again, awesome work, thank you very much. I didn't see a place to approve the PR, not that's my approval is needed, but I'll leave an approving and grateful comment. You're quick attention to issues and actions to improve and enhance makes express-zod-api great to work with. Thanks Robin!

[RobinTail]

Awesome, @lpw ! Thank you for testing it.
🚀 v16.7.0 released.