Swagger API

[Swagger](http://swagger.wordnik.com/) is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. ServiceStack implements basic API in a separate plugin which is available under NuGet package: [ServiceStack.Api.Swagger](http://nuget.org/packages/ServiceStack.Api.Swagger/).

## Installation

Default configuration expects that ServiceStack services are available under ‘/api’ path. For services hosted at custom paths, e.g. ‘/service-stack’, set the ‘discoveryUrl’ configuration property of swagger initialization script (located in your /swagger-ui/index.html file) as given below:

File: '/swagger-ui/index.html'
...
<script type="text/javascript">
        $(function () {
            window.swaggerUi = new SwaggerUi({
             // discoveryUrl:'../api/resources' /* old value */
                discoveryUrl:'../service-stack/resources',  /* new value */
                apiKey:"",
                dom_id:"swagger-ui-container",
                supportHeaderParams: false,
                supportedSubmitMethods: ['get', 'post', 'put']
            });

            window.swaggerUi.load();
        });
</script>
...

If it’s a brand new MVC project install NuGet Package: (http://nuget.org/packages/ServiceStack.Host.Mvc/) which prepares ServiceStack default services. Make sure that you added ignore for MVC routes:

routes.IgnoreRoute("api/{*pathInfo}"); 

If it’s MVC4 project, then don’t forget to disable WebAPI:

//WebApiConfig.Register(GlobalConfiguration.Configuration);

Enable Swagger plugin in AppHost.cs with:

  public override void Configure(Container container)
  {
      ...
      Plugins.Add(new SwaggerFeature());

      // uncomment CORS feature if it's has to be available from external sites 
      //Plugins.Add(new CorsFeature()); 
      ...
  }

Compile it. Now you can access swagger UI with:

[http://localost:port/swagger-ui/index.html](http://localost:port/swagger-ui/index.html)

or

[http://yoursite/swagger-ui/index.html](http://yoursite/swagger-ui/index.html)

## Swagger Attributes

Each route could have a separate summary and description. You can set it with `Route` attribute:

[Route("/hello", Summary = @"Default hello service.", Notes = "Longer description for hello service.")]

You can set specific description for each HTTP method like shown below:

  [Route("/hello/{Name}", "GET", Summary = @"Says ""Hello"" to provided Name with GET.", 
      Notes = "Longer description of the GET method which says \"Hello\"")]
  [Route("/hello/{Name}", "POST", Summary = @"Says ""Hello"" to provided Name with POST.", 
      Notes = "Longer description of the POST method which says \"Hello\"")]

You can further document your services in the Swagger UI with the new `[Api]` and `[ApiMember]` annotation attributes, e,g: Here’s an example of a fully documented service:

[Api(“Service Description”)] [Route(“/swagger/{Name}”, “GET”, Summary = @”GET Summary”, Notes = “GET Notes”)] [Route(“/swagger/{Name}”, “POST”, Summary = @”POST Summary”, Notes = “POST Notes”)] public class MyRequestDto { [ApiMember(Name=”Name”, Description = “Name Description”, ParameterType = “path”, DataType = “string”, IsRequired = true)] public string Name { get; set; } }

The complete list of available types could be find in [Swagger documentation](https://github.com/wordnik/swagger-core/wiki/Datatypes).

## Demo Project

ServiceStack.UseCases project contains example [SwaggerHelloWorld](https://github.com/ServiceStack/ServiceStack.UseCases/tree/master/SwaggerHelloWorld). It demonstrates how to use and integrate [ServiceStack.Api.Swagger](http://nuget.org/packages/ServiceStack.Api.Swagger/). Take a look at [README.txt](https://github.com/ServiceStack/ServiceStack.UseCases/blob/master/SwaggerHelloWorld/README.txt) for more details.