Support for swagger JSON needs more documentation and error handling

[dantaub]

re: 0c999c9#r29816386

There is not always a definition for every title. Often, the title and the route names differ, or there is a route with no corresponding model. When they do correspond, they are linked by 'ref' -- take for example the simple petstore definition:

https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json

For starters, the route name and the definition name differ by capitalization.

In many other APIs, some routes do not have associated model definitions. For example the 'store' route in: https://petstore.swagger.io/v2/swagger.json

I do see how this could be used by ensuring every route is tagged with the same name, so this fact needs to be documented. Also, it should fallback to checking alternate forms based on capitalization/pluralization. Finally, it should fail more gracefully when a route does NOT have a related model definition, so those that do still are processed correctly.

[arojunior]

Thanks for this feedback @dantaub and sorry about the delay. That implementation was made by me and I'm going to make this improvements.
The problem is that the maintainers of this repository take a long to respond pull requests and issues, but I will try to help you anyway.