what is swagger exactly ? And why doesn't the online editor run requests?

Question

I've spent the last few days trying to understand if I should use api blueprint, RAML or swagger.

It looks like swagger has the biggest community but the closer I look the more I feel that it greatly lacks in documentation (I was forced to look at the code many times to try and integrate it with my current project), many github issues and stackoverflow questions are unanswered.

Is it possible that I am missing something here? All I want is a tool to help me write the API documentation and test the endpoints.

Why must swagger become part of the server logic?? If I create swagger files in the editor and then serve them to the UI directly it breaks..

As far as I can tell it even makes the server slightly slower and forces the existence of many clumsily maintained integrations :p What am I missing here?

Answer 1

We're trying to work a lot on improving the documentation of Swagger. It's a bit more difficult when many of the projects are community-driven and not managed by a single organization.

We actually try to reply to issues on github quickly (we don't always succeed) and we have our own google group for general questions so we follow stackoverflow somewhat less.

The editor you mention is a new tool as part of the work on Swagger 2.0 and it's not final yet. As such, it still have a few bugs and missing features. The UI is also in the process of being adapted to Swagger 2.0 and the same limitations apply to it.

You most certainly don't have to integrate it with your server and you can expose the documentation statically. The advantage of integrating it with the server is that it's easier to maintain if the API changes.

Answer 2

You can try RAML + ramlev + Abao

The steps should be

• Write API Spec in RAML with your fav editor, ie. Atom, vim
• Validate your RAML with ramlev
• Implement the server logic according API Spec
• Validate server logic with Abao