Do whatever it takes to appears cowboy-swagger on "http://swagger.io/open-source-integrations/"

[cabol]

Do whatever it takes to appears cowboy-swagger on "http://swagger.io/open-source-integrations/"

[webron]

Funny, I was just about to invite you and ask whether you'd like to be added there.

One question though, on one hand, it seems you're producing Swagger 2.0, on the other, you're using the < 2.0 convention of exposing your definitions (i.e., /api-docs vs swagger.json/swagger.yaml). So which version do you actually expose?

[cabol]

Hi.

First, thanks for your comment. The idea is to expose 2.0, we didn't know that we were using < 2.0 conventions, so according to that and to be compliant with 2.0 spec, how should the path be called (i.e. instead of /api-docs)?

[webron]

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#file-structure

By convention, the Swagger specification file is named swagger.json.

That's of course for the JSON format. For YAML it should be swagger.yaml (and yes, you should expose both).

Keep in mind you're not required to expose it this way, but you should :)

[cabol]

Ok, I understand, but other thing you should be aware, to load the JSON the path to be called is: /api-docs/swagger.json, that is what the embedded Swagger-UI does (https://github.com/inaka/cowboy-swagger/blob/master/priv/swagger/index.html#L36). Besides, there is a Cowboy handler that is in charge to respond all request to that path. Our idea behind this was group all resources related with swagger's doc under the same path (/api-docs), avoiding that routes be overlapped each other, since the app using cowboy-swagger could have its own static content and handlers that probably will work under the root path /. For that reason we decided isolate the cowboy_swagger routes and group them under /api-docs, but there isn't a particular/logical reason for that name.

According to that, do you think that we should rename that path? if so, any suggestions for the name?

[webron]

Again, we don't enforce anything, so it's entirely up to you. I just believe that exposing it with the same name in a similar 'logic' across applications, makes it easier for users to access regardless of the development language.

I understand the wish to avoid conflicts, but I somewhat doubt anyone is going to expose a swagger.json endpoint on their own at the root of the application. In the same way, you could argue that someone may want to expose a /api-docs endpoint and you have the same problem. I'm not familiar with erlang nor cowboy, so I don't know if you can set a default hosted location and allow the user to change it based on some configuration. I can tell you that in swagger-core it's pretty much hard-coded and hosted at the context root of the application.

[cabol]

Ok, you're right! I'll create an issue to fix it following your suggestions.

Thanks again!

[webron]

Cool. Feel free to submit a PR against https://github.com/swagger-api/swagger.io/blob/wordpress//integrations/open-source.md to add your library. Keep in mind that you need to add a new title + table (at the right place) for erlang since it's the first erlang implementation we have (woot!).

[elbrujohalcon]

Already there :)