ServiceStack/ServiceStack — pull request #639 by mmertsock (2013-04-29 13:44:36+00:00)
Title: Add request/response schemas and sample JSON to Swagger UI

Adds "models" and "responseClass" elements to the response DTOs of the `SwaggerApiService`. This allows the Swagger UI to describe the structure of request and response objects, and also to display automatically generated sample JSON for request body parameters. To support these UI changes, it was also necessary to update the Swagger UI HTML/JS/CSS to the [latest stable version (1.1.7)](https://github.com/wordnik/swagger-ui/tree/v1.1.7).

The model data is automatically generated in `SwaggerApiService` via reflection on the request and response DTO properties, and by looking for certain attributes. In addition to the `ApiMember` and `SwaggerAllowableValues` attributes, it will now look for `System.ComponentModel.DescriptionAttribute` attributes to allow adding descriptions for properties of DTOs without exposing them as a separate request parameter in the Swagger UI, as would happen when using `ApiMemberAttribute`.

I am sure there are some edge cases not yet handled in this implementation (e.g. not correctly representing nested lists or other complex data types in the Swagger UI), but any such cases should not really break the UI. The worst that should happen is that the UI may show some incomplete sample JSON or have some funny looking descriptions of model/response classes. But I feel something is better than nothing. If there are concerns about this, perhaps we should add a property to `SwaggerFeature` to opt-in to the new model schema documentation so that existing implementations don't have unexpected UI changes.

The changes are localized to the `ServiceStack.Api.Swagger` project, except for a couple of extension methods added to `StringExtensions.cs` in `ServiceStack.Common`. These are just wrappers for some extension methods in `ServiceStack.Text`; currently `ServiceStack.Api.Swagger` does not have a direct dependency of ServiceStack.Text so I did not want to add that dependency myself. These wrapper extension methods allowed me to avoid adding the dependency.

Although some JS/CSS files were added, and some were renamed/removed, it appears that no changes are needed for `ServiceStack.Api.Swagger.nuspec`, since the nuspec file uses wildcards to reference these files.