Alterative route declaration about open-api

[jsdevel]

Re-opening as express-openapi should aim to be as un-opinionated as possible to follow express's purpose Fast, unopinionated, minimalist web framework for Node.js.

[mika-fischer]

Yes, that also sounds fine, I'll see if I can implement this this week.

[jsdevel]

So you can define paths in apiDoc.paths, and express-openapi will inherit from it, except for handlers.

What you would consider limiting, I would consider freeing.

Consider that you never have to duplicate a path, as it's entirely inferred from fs.

[jsdevel]

Also, your documentation is kept up to date for users. So if you delete a handler, you don't have to worry about your docs getting out of sync. This is what bothers me about other frameworks that expect a monolithic json document or yaml doc to describe their apis.

[MugeSo]

OpenAPI spec has $ref for Path Object

[DaleLJefferson]

Thanks for re-opening this, it sounds like we could pull out the current convention over configuration router part of express-openapi into a separate middleware.

BTW I've successfully used a few of the express-openapi middleware with Koa, the middleware strategy you have chosen works really nicely.

[jsdevel]

@dalejefferson glad to hear the middleware strategy is working out for you!

I've had a few thoughts related to closing out this ticket:

• Add a new argument to the initialization args that specifies either a module or a directory (haven't decided which would be more friendly).
• This argument will define the operation handlers for the provided apiDoc.
• Operation handlers are referenced via operationId in the apiDoc.

[mika-fischer]

A related issue is that the reliance on fs-routes makes it totally impossible to package an app using express-openapi using webpack or similar tools. I'd like to be able to provide express-openapi with a list mapping urls to module paths or already loaded modules.

[jsdevel]

@mika-fischer PRs are always welcome!

[mika-fischer]

@jsdevel I might give it a go. But what would your preferred API look like?

My idea would be to make the paths option optional, and add a new option (maybe routes or urls(?)) and allow to pass an array of objects: [ { route: 'foo', module: require('foo') }, ... ] or [ { route: 'foo', path: 'foo' }, ... ], similar to what fs-routes generates.

That way most of the code could be reused...

[jsdevel]

@mika-fischer I think the paths option array could also contain objects, and if no strings are in the array then we can skip the fs-routes call. Thoughts?

[jsdevel]

@dalejefferson see the great work @mika-fischer did in #60. I feel it closes this issue. Thoughts?

[DaleLJefferson]

Thanks @mika-fischer this looks great, I will happily close this issue