W dwóch postach poruszałem już temat dokumentacji usług REST. Ręczne tworzenie plików JSON dla swagger jest dosyć czasochłonne i łatwo potem zapomnieć przy jakiś modyfikacjach o aktualizacji dokumentacji.

Dla ASP.NET MVC WebAPI na szczęście jest Swashbuckle. Zacznijmy od instalacji odpowiedniego pakietu:

Install-Package Swashbuckle

Zobaczymy, że został dodany m.in. plik SwaggerConfig.cs. Wpisując teraz adres /swagger np. “http://localhost:35447/swagger” ujrzymy automatycznie wygenerowaną dokumentację:

Polecam również włączenie komentarzy XML, jak to było w przypadku ASP.NET HelpPages. Przechodzimy do właściwości projektu i zaznaczamy XML Documentation File:

Następnie możemy odkomentować następującą linię:

c.IncludeXmlComments(GetXmlCommentsPath());

Gdzie GetXmlCommentsPath to:

private static string GetXmlCommentsPath()
{
    return System.String.Format(@"{0}\App_Data\XmlDocument.xml", System.AppDomain.CurrentDomain.BaseDirectory);
}

Teraz w komentarzach możemy określić parametry, zwracane kody itp.:

public class SampleController : ApiController
{
    /// <summary>
    /// Any method description
    /// </summary>
    /// <param name="id">Id of something</param>
    /// <remarks>Any remarks</remarks>
    /// <response code="400">Bad request</response>
    /// <response code="500">Internal Server Error</response>
    public int Test(int id)
    {
        return 0;
    }
}

Przechodząc do Swagger, zobaczymy: