How to integrate a spec from constructing OpenAPI into an endpoint

[lpw]

Thanks for this nice framework, leveraging types, more declarative APIs (which is one thing I liked about hapi over express).

I've got my API endpoints built, working great. I've got the OpenAPI spec constructed from those same routes, also working great.

I've tried various ways to build and add an endpoint to serve the spec's yaml/json via swagger-ui-express, but the few attempts I've tried don't quite work correctly. I'm avoiding the usual app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)) method as it seems antithetical to the way other endpoints are declared (and also, at least by default, /api-docs route would then be blocked by createNotFoundHandler introduced in #154)

Perhaps I'm missing something fundamental and/or obvious. Is swagger-ui-express the best package to use with express-zod-api to render the resulting spec? If not, what is? If so, are there any examples, templates, hints for using them together?

Thanks, -Lance.

[RobinTail]

Hello @lpw ,

I never tried using swagger-ui-express, but reading its documentation I figured out that it consists of two parts: some express middleware and the handler that serves an HTML page, so that route is not a part of the API.

In this regard, I believe, you should switch to custom app approach and attachRouting() method instead of createServer().

You should create your own express app, apply app.use() the way swagger-ui-express recommends, then attachRouting() and start listening the requests. Check out the example in the Readme.

Please try this approach and let me know if it works.

[lpw]

Indeed I gave up on serving swagger via the API endpoints made in express-zod-api, allowing swagger-ui-express to serve them directly as designed. Seems right in hindsight - the request and response structures were different, was going down a hole trying to reconcile them between the two packages.

However, I'm still using createServer() - I've overridden the default errorHandler so that it doesn't 404 the swagger endpoint. Seems to be working well, but maybe I'll create my own server app and switch to attachRouting() per your comment.

Thanks for your reply - lots of great work in this package, and in keeping the discussions going. Still curious how others are serving documentation from their express-zod-api APIs if not via swagger-ui-express.