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 REST API (bez HATEOAS, s verzováním pomocí URI) a pomocí NuGet balíčků OpenAPI a Swagger UI vytvoříme dokumentaci přístupnou z webu. Tuto dokumentaci si následně 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 automaticky se nám nainstaluje 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"));

Nyní 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

Dokumentace je připravena k použití, ale ještě si ji vylepšíme 🚀

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

Do Swagger dokumentace přidáme 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 jinak zobrazovala u většiny veřejných metod a proměnných.

Swagger službě dáme vědět, že si má načítat komentáře z nově generovaného souboru WebApi.xml.

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

Nyní upravíme náš API endpoint a přidáme komentáře včetně atributu summary.

• Endpoint obsahuje nový vstupní objekt ForecastHorizontInputModel, který obsahuje proměnnou se summary komentářem a required atributem. Komentář s atributem se v dokumentaci také projeví.

/// <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 naše API obsahuje více endpointů, může být přehlednější rozdělit OpenAPI dokumentaci na více stránek. Toho dosáhneme pomocí atributu ApiExplorerSettings a úpravy ve startup.cs. Jako příklad přidáme 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 vyví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 atd.). Pokud klient není pod naší správou, měli bychom mít pro takové případy připravenou verzovací strategii. Verzovacích strategií je několik a každá má své výhody i nevýhody.

V tomto případě budu specifikovat verzi přímo v URL adrese (URI neboli také URL path-based verzování). Dokumentace bude rozdělena podle jednotlivých verzí, nikoliv nutně podle jednotlivých kontrolerů, jak jsme to 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í. Konkrétní 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 informovat knihovny Swagger a Swagger UI. 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 trochu je 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 ve výchozím stavu endpointy seskupuje pod názvy kontrolerů, 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ý nainstalujeme a nastavíme.

dotnet add package Swashbuckle.AspNetCore.Annotations

Zaregistrujeme službu options.EnableAnnotations();

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

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 jsme prošli nastavení, jak pomocí OpenAPI a Swagger UI vytvořit základní dokumentaci pro naše API endpointy. 🤗

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í