Swagger API

Swagger 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.

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:

<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

or

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")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")][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)]
    [ApiAllowableValues("Name", typeof(Color))] //Enum
    public string Name { get; set; }
}

The complete list of available types could be find in Swagger documentation.

Demo Project

ServiceStack.UseCases project contains example SwaggerHelloWorld. It demonstrates how to use and integrate ServiceStack.Api.Swagger. Take a look at README.txt for more details.