Slovníček

Obsah

• Úvod
• Příprava API
• Přidání podpory pro XML komentáře
• Rozdělení dokumentace na více stránek
• Verzování
  • Nastavení
  • Promítnutí do dokumentace
  • Úprava seskupení
• Závěr
• Odkazy

Úvod

Připravíme si REST API (bez HATEOAS a s URI verzováním) a pomocí OpenAPI a Swagger UI Nuget balíčků vytvoříme přes web přístupnou dokumentaci, kterou si pak může zobrazit kdokoliv, kdo bude s API pracovat.

Příprava API

Vytvoříme si WebAPI projekt. WebAPI šablona ve výchozím nastavení již OpenAPI podporuje a nainstaluje se nám doplněk Swashbuckle.AspNetCore.

dotnet new webapi

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "rest", Version = "v1" });
});

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "rest v1"));

a zároveň máme k dispozici výchozí WeatherForecastController. Pokud API spustíme a přejdeme na stránku /swagger/index.html zobrazí se nám následující interaktivní dokumentace

máme tedy k dispozici velmi užitečný nástroj, nicméně jsme ještě neskončili a dokumentaci si vytuníme 😂🚀

Přidání podpory pro XML komentáře

Vygenerovanou Swagger dokumentaci můžeme obohatit o naše vlastní komentáře, které si ale musíme nejdříve povolit v Project > Properties > Build: Output. Zároveň potlačíme chybovou hlášku CS1591: Missing XML comment for publicly visible type or member, která by se nám jinak zobrazovala u většiny veřejných metod a proměnných.

Dáme swagger službě vědět, že si má načíst WebApi.xml.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" });
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "WebApi.xml"));
});

A teď už si můžeme upravit naší API metodu. Metoda má summary a remarks komentář a také nově přijímá vstupní parametr objekt. Objekt obsahuje proměnnou se summary komentářem a required atributem, který se v dokumentaci také projeví. Do XML komentářů nelze psát speciální znaky a musíme je v případě potřeby nahradit.

/// <summary>
/// Get temperature in Celsius for each date.
/// </summary>
/// URL request example&#x003A; 
/// 
///     /weatherforecast?dates=2020-05-01&amp;dates=2020-05-02
///     
[HttpGet]
public IActionResult Get([FromQuery]ForecastHorizontInputModel model)
{
    // ...
    return Ok(result);
}

public class ForecastHorizontInputModel
{
    /// <summary>Collection of dates. Each date can be between 2020-01-01 and five days in advance.</summary>
    [Required]
    public List<DateTime> Dates { get; set; }
}

Rozdělení dokumentace na více stránek

Pokud má naše API hodně endpointů, může být přehlednější rozdělit Open API dokumentaci na více stránek. Toho dosáhneme pomocí ApiExplorerSettings atributu a úpravy ve startup.cs. Pro příklad přidám nový EarthquakeAlertController, který bude mít samostatnou Swagger UI stránku.

// WeatherForecastController.cs
[ApiController] 
[Route("[controller]")]
[ApiExplorerSettings(GroupName = "weather")]
public class WeatherForecastController : ControllerBase

// EarthquakeAlertController.cs
[ApiController]
[Route("[controller]")]
[ApiExplorerSettings(GroupName = "earthquake")]
public class EarthquakeAlertController : ControllerBase

// ConfigureServices
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("weather", new OpenApiInfo { Title = "Weather Forecast", Version = "v1" });
    c.SwaggerDoc("earthquake", new OpenApiInfo { Title = "Earthquake Alert", Version = "v1" });
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "WebApi.xml"));
});

// Configure
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/weather/swagger.json", "Weather API");
    c.SwaggerEndpoint("/swagger/earthquake/swagger.json", "Earthquake API");
});

Group name, Swagger Doc name a Swagger Endpoint name v cestě se musí rovnat. Mezi kontrolerama pak můžeme v dokumentaci snadno přepínat.

Verzování

Naše API se může rozvíjet a může nastat potřeba implementovat tzv. breaking změnu, která by mohla znefunkčnit případného API klienta (například zrušení endpointu, změna vstupního parametru, změna odpovědi, ...). Pokud klient není pod naší kontrolou, měli bychom mít pro takové případy připravenou verzovací strategii. Verzovacích strategií je několik a každá má své pro a proti. V tomto případě budu specifikovat verzi přímo v URL adrese (URI neboli také URL path based verzování). Dokumentace bude tedy rozdělená podle jednotlivých verzí nikoliv nutně podle jednotlivých kontrolerů (jako jsme ručně nastavili výše).

Nastavení

Vytvoříme si nový projekt

dotnet new demoapi

Přidáme podporu pro verzování v podobě Nuget balíčku Microsoft.AspNetCore.Mvc.Versioning, který zaregistrujeme jako middleware ve Startup.cs.

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

public void ConfigureServices(IServiceCollection services)
{
  //...
  services.AddApiVersioning(options =>
  {
    // Add response headers "api-supported-versions" and "api-deprecated-versions"
    options.ReportApiVersions = true;
  });

  services.AddVersionedApiExplorer(options =>
  {
    // Setup format such as v1.0
    options.GroupNameFormat = "'v'VV";

    // Set to true when URL path based versioning is in use
    options.SubstituteApiVersionInUrl = true;
  });
  //...
}

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/WeatherForecast")]
public class WeatherForecastController : ControllerBase

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/WeatherForecast")]
public class WeatherForecastV2Controller : ControllerBase

Při vytváření nové verze není potřeba duplikovat všechny metody (tedy i ty, které se nezměnily), ale lze použít atribut MapToApiVersion, pomocí kterého si můžeme nadefinovat, které metody jsou součástí, kterých API verzí (metoda tedy může být součástí předchozí i nové verze). Nyní nám budou fungovat následující odkazy:

• /api/v1.0/WeatherForecast
• /api/v2.0/WeatherForecast

Promítnutí do dokumentace

O verzování musíme dát vědět Swagger a SwaggerUI knihovnám a pro tento účel jsem si vypůjčil třídy z následujícího blogu, na který jsem při psaní tohoto článku narazil a pouze jsem je drobně upravil. Vytvoříme tedy následující třídy:

using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace DemoApi.Swagger
{
    /// <summary>
    /// Configures the Swagger generation options.
    /// </summary>
    /// <remarks>This allows API versioning to define a Swagger document per API version after the
    /// <see cref="IApiVersionDescriptionProvider"/> service has been resolved from the service container.</remarks>
    public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
    {
        private readonly IApiVersionDescriptionProvider _provider;

        /// <summary>
        /// Initializes a new instance of the <see cref="ConfigureSwaggerOptions"/> class.
        /// </summary>
        /// <param name="provider">The <see cref="IApiVersionDescriptionProvider">provider</see> used to generate Swagger documents.</param>
        public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) => _provider = provider;

        /// <inheritdoc />
        public void Configure(SwaggerGenOptions options)
        {
            // add a swagger document for each discovered API version
            // note: you might choose to skip or document deprecated API versions differently
            foreach (var description in _provider.ApiVersionDescriptions)
                options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
        }

        private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
        {
            var info = new OpenApiInfo()
            {
                Title = "Web API",
                Version = description.ApiVersion.ToString(),
                Description = "Web API to Forecast Weather."
            };

            if (description.IsDeprecated)
                info.Description += " This API version has been deprecated.";

            return info;
        }
    }
}

using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;

namespace DemoApi.Swagger
{
    /// <summary>
    /// Represents the Swagger/Swashbuckle operation filter used to document the implicit API version parameter.
    /// </summary>
    /// <remarks>This <see cref="IOperationFilter"/> is only required due to bugs in the <see cref="SwaggerGenerator"/>.
    /// Once they are fixed and published, this class can be removed.</remarks>
    public class SwaggerDefaultValues : IOperationFilter
    {
        /// <summary>
        /// Applies the filter to the specified operation using the given context.
        /// </summary>
        /// <param name="operation">The operation to apply the filter to.</param>
        /// <param name="context">The current operation filter context.</param>
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            var apiDescription = context.ApiDescription;

            operation.Deprecated |= apiDescription.IsDeprecated();

            // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1752#issue-663991077
            foreach (var responseType in context.ApiDescription.SupportedResponseTypes)
            {
                // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/b7cf75e7905050305b115dd96640ddd6e74c7ac9/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L383-L387
                var responseKey = responseType.IsDefaultResponse ? "default" : responseType.StatusCode.ToString();
                var response = operation.Responses[responseKey];

                foreach (var contentType in response.Content.Keys)
                    if (responseType.ApiResponseFormats.All(x => x.MediaType != contentType))
                        response.Content.Remove(contentType);
            }

            if (operation.Parameters == null)
                return;

            // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/412
            // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/413
            foreach (var parameter in operation.Parameters)
            {
                var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);

                parameter.Description ??= description.ModelMetadata.Description;

                if (parameter.Schema.Default == null && description.DefaultValue != null)
                {
                    // REF: https://github.com/Microsoft/aspnet-api-versioning/issues/429#issuecomment-605402330
                    //var json = JsonSerializer.Serialize(description.DefaultValue, description.ModelMetadata.ModelType);
                    //parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);

                    parameter.Schema.Default = OpenApiAnyFactory.CreateFor(parameter.Schema, description.DefaultValue);
                }

                parameter.Required |= description.IsRequired;
            }
        }
    }
}

Upravíme Swagger konfiguraci ve Startup.cs

// ConfigureServices
services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

services.AddSwaggerGen(options =>
{
    options.OperationFilter<SwaggerDefaultValues>();
});

// Configure
app.UseSwagger(options => { options.RouteTemplate = "swagger/{documentName}/docs.json"; });
app.UseSwaggerUI(options =>
{
    options.RoutePrefix = "swagger";
    foreach (var description in provider.ApiVersionDescriptions)
        options.SwaggerEndpoint($"/swagger/{description.GroupName}/docs.json", description.GroupName.ToUpperInvariant());
});

Nyní máme k dispozici automatickou dokumentaci pro oba kontrolery, která se bude aktualizovat podle nastavení jednotlivých verzí.

Úprava seskupení

Swagger si ve výchozím stavu endpointy seskupuje pod název kontroleru, proto máme pro v1 WeatherController a pro v2 WeatherControllerV (dvojka z názvu nějak vypadla). Oba názvy nejsou úplně uživatelsky přívětivé, ale naštěstí máme možnost je upravit a sjednotit. K tomu poslouží Nuget balíček Swashbuckle.AspNetCore.Annotations, který si nainstalujeme a nastavíme.

dotnet add package Swashbuckle.AspNetCore.Annotations

Zaregistrujeme službu options.EnableAnnotations();

services.AddSwaggerGen(options =>
{
    options.OperationFilter<SwaggerDefaultValues>();
    options.EnableAnnotations();
});

A můžeme definovat skupinu, do které má endpoint spadat. Nadefinovaných skupin může být v rámci jednoho kontroleru klidně i několik.

[HttpGet]
[SwaggerOperation(Tags = new[] { "Weather" })]
public IEnumerable<WeatherForecast> Get()

Závěr

V tomto článku jsem se snažil projít nastavení, které můžeme použít pro zdokumentování našeho API. Možností jak si dokumentaci přizpůsobit je více, ale myslím, že již nyní jsme schopní vytvořit celkem užitečnou dokumentaci 😀.

Odkazy

• REST API definice
• Popis HATEOAS
• Výhody a nevýhody HATEOAS
• REST Maturity Model
• Popis verzovacích strategií
• Jak verzovat API
• Jak verzovat API
• Jak verzovat API
• Jak verzovat API a propojení se Swagger UI
• Jak změnit jméno kontroleru, seskupování pomocí anotací