question: best way to serve swagger doc to swagger ui?

[emcpadden]

I am trying out a127/volos and I have a question about the best way to show the swagger ui from the swagger yaml file that is edited in the a127 generated project. I am new to swagger and a127/volos so forgive me if I am asking a dumb question.

I was thinking that I could have my api project (which was generated with a127) serve up a swagger.json file that swagger ui could display. I see that a127 generates and edits the swagger.yaml file in the project. I was wondering how I would go about serving that up from the running api to swagger ui. As far as I know, swagger ui takes a json file not a yaml file.

Down the road, I thought that I could create a dev portal that could point at the api to get the swagger doc to display and allow the user to exercise the api from the swagger ui.

Any help or direction you can point me in would be helpful. I was on a previous project using node and express but I am far from an expert on express.

Thanks!!!
...Ed

[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.