question: best way to serve swagger doc to swagger ui? about a127-documentation

[emcpadden]

I think I just figured it out, please tell me if this is a good way to do this or if I should be doing something else.

After debugging through it, and also looking at the swagger tools project, I saw that I could do the following in my app.js (which was generated using a127):

a127.init(function(config) {
app.use(a127.middleware(config));

app.use(config['a127.magic'].swaggerTools.swaggerUi());

app.listen(process.env.PORT || 10010);
console.log('try this:\ncurl http://127.0.0.1:10010/hello?name=Scott');
});

Is this the preferred way to do this?

Thanks,
...Ed

[theganyo]

I honestly don't know if there is a preferred way to do this... I do know there is a plan to make Swagger Editor be able to provide the capabilities of Swagger UI (and more) and expose that functionality via configuration. In the meantime, your solution can work... I just can't guarantee it will continue to do so as it relies on implementation details in a127-magic.

[emcpadden]

OK, thanks Scott. It might be nice if the swagger tools was exposed directly off the config or some other way we could rely on. There is a lot of nice stuff in there that would be great to get at in a reliable way. I would think it would always be there because I think you are already using it for the validation.

Thanks again Scott for the quick reply, it helps a lot as I wrap my head around this stuff.

[theganyo]

True, swagger-tools is likely to always be there. My point is just that since we encapsulate it and don't document access to it, I would consider it "unsupported". What functionality are you interested in accessing from swagger-tools that we don't already expose?

[emcpadden]

Good point, I guess the things I would really want out of the swagger tools is a way to view the swagger UI and to be able to get the swagger doc in json so that it could be potentially displayed in a dev portal.

For this, maybe if there was an easy way to setup the middleware to optionally expose a /doc and /api-docs route and hide the fact that it comes from the swagger tools ... that would definitely work for me.

In looking further at the swagger tools, I agree that exposig all of that is probably not a great idea since it has way more stuff than I think anyone would need outside the internals.