shared model support, resource overview support

[andycmaj]

Changes

1. rename operation.errorResponses -> operation.statusCodes.
   • Better indicate that people can use this property to represent all status codes returned from an operation
   • Will break swagger-ui without incorporating accompanying change in related pull request.
2. add shared model support
   • Allows definition in one file of shared models that can be referenced from many resources. Avoid having to copy and paste model definitions between resource definitions
3. add resource overviews: allows general documentation overview for an entire resource.

These changes will enable the improvements in the Swagger client. In order to display in swagger-ui, see accompanying pull request in swagger-ui.

See example here: http://andycmaj.github.io/swagger-sandbox.

[jwyuen]

Bump! Would really like to see this implemented for DRY purposes.

[andycmaj]

Yes... so would I!

[fehguy]

Howdy, this is an old PR and much of the DRY work has gone into the 2.0 spec for swagger. If you'd like to get involved in that, please see here:

http://swagger.wordnik.com

We can't change the 1.2 spec without breaking a bunch of clients & tooling. So 2.0 is the chance for improved spec design.