Alıştırma - OPENAPI belgelerinizi XML açıklamaları ve ek açıklamaları ile özelleştirme ve genişletme

  • 12 dakika

Bu alıştırmada, kodunuz için açıklamalar ve ek açıklamalar ekleyerek bir geliştiricinin API'niz hakkında gördüğü belgeleri zenginleştireceksiniz. İlk olarak Swagger UI tarafından varsayılan olarak oluşturulan belgelere bakalım.

  1. Swagger kullanıcı arabiriminde API'mizin uç noktasının OpenAPI tanımını incelemek için tarayıcınızda adresine http://localhost:5000/swagger gidin. Get yöntemini seçtiğinizde aşağıdakine benzer bir çıktı görmeniz gerekir.

    Default Swagger UI for our API.

    Swagger UI, API hakkında faydalı bilgiler sağlar. Çağırabileceğiniz yöntemleri gösterir (basit örneğinizde PriceFrame adlı bir yöntem). Bunun Height ve Width adlı iki gerekli parametreyi alan bir HTTP Get işlemi olduğunu görebilirsiniz. API Çağrısının nasıl çalıştığını görmek için Deneyin'i seçebilir, Yükseklik ve Genişlik değerlerini girebilir ve Yürüt'i seçebilirsiniz.

    API kullanıcılarınız hala PriceFrame yönteminin sınırlamalarını bilmek için yeterli bilgiye sahip değil. Şimdi XML açıklamalarıyla daha ayrıntılı bilgi sağlayarak onlara yardımcı olalım.

API'nize XML açıklaması ekleme

  1. Son alıştırmada kullandığınız Visual Studio Code örneğine geri dönün.

  2. Web API'si son alıştırmada çalışmaya devam ediyorsa, durdurmak için Windows'ta ctrl+c veya Mac'te cmd+c tuşlarına basın.

  3. Projenizde XML belgelerini etkinleştirmek için PrintFramerAPI.csproj proje dosyasını güncelleştirinGenerateDocumentationFile, etiketi var olan <PropertyGroup>öğesine ekleyin ve olarak trueayarlayın.

    <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

  4. Startup.cs dosyasına aşağıdaki using deyimlerini ekleyin.

    using System.Reflection;
using System.IO;

  5. Startup.cs'de Swashbuckle'a içindeki çağrısının AddSwaggerGen() ConfigureServicesgüncelleştirilerek XML belgelerini kullanmasını söyleyin.

     public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();

     // Register the Swagger generator, defining 1 or more Swagger documents
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo
         {
             Version = "v1",
             Title = "PrintFramer API",
             Description = "Calculates the cost of a picture frame based on its dimensions.",
             TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"),
             Contact = new OpenApiContact
             {
                 Name = "Your name",
                 Email = string.Empty,
                 Url = new Uri("https://learn.microsoft.com/training")
             }
         });

         // Set the comments path for the Swagger JSON and UI.
         var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
         var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
         c.IncludeXmlComments(xmlPath);
     });
 }

    Yukarıdaki kodda yansıma, XML açıklamalarını yüklenecek XML dosyasının adını belirler.

  6. Denetleyiciler klasöründe PriceFrameController.cs dosyasını açın. Yönteminin HttpGet özniteliğinin üzerine aşağıdaki XML açıklama bloğunu GetPrice ekleyin. Bir eyleme üç eğik çizgiyle açıklama eklediğinizde bölüm üst bilgisine açıklama eklenir ve Swagger UI geliştirilir.

     /// <summary>
 /// Returns the price of a frame based on its dimensions.
 /// </summary>
 /// <param name="Height">The height of the frame.</param>
 /// <param name="Width">The width of the frame.</param>
 /// <returns>The price, in dollars, of the picture frame.</returns>
 /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks>
 [HttpGet("{Height}/{Width}")]
 public string GetPrice(string Height, string Width)
 {
     string result;
     result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
     return $"The cost of a {Height}x{Width} frame is ${result}";
 }

  7. Tüm değişiklikleri kaydetmek ve yerel olarak derlediğinden emin olmak için Visual Studio Code terminal penceresinde aşağıdaki komutu çalıştırın.

    dotnet build

  8. Değişikliklerinizi görmek için Visual Studio Code terminal penceresine aşağıdakileri girerek ASP.NET uygulamasını yerel olarak çalıştırın:

    dotnet run

  9. konumunda Swagger kullanıcı arabirimine yeniden http://localhost:5000/swaggerbakın ve XML açıklamalarınızın OpenAPI belgelerine sağladığı ek bilgileri inceleyin.

    Swagger UI with the final documentation from XML comments for our API.

API'nize veri açıklaması ekleme

Swagger'ın OpenAPI belgelerini geliştirmesini sağlamak için ad alanından Microsoft.AspNetCore.Mvc öznitelikleri kullanırsınız.

  1. Web API'si son alıştırmada çalışmaya devam ediyorsa, durdurmak için Windows'ta ctrl+c veya Mac'te cmd+c tuşlarına basın.

  2. API'nizin GetPrice metin/düz için içerik türü yanıtını desteklediğini göstermek için, API denetleyicisi olan PriceFrameController.cs dosyasında tanımın GetPrice üzerine bir [Produces("text/plain")] öznitelik ekleyin.

    [HttpGet("{Height}/{Width}")]
[Produces("text/plain")]

    Yanıt İçerik Türü açılan menüsü, denetleyicinin GET eylemleri için varsayılan olarak bu içerik türünü seçer.

API'nize Swashbuckle ek açıklamaları ekleme

Şu ana kadar API'niz verilen çerçeve boyutları için bir fiyat hesapladığında 200 durum kodunu döndürür. Yöntemin açıklamasında GetPrice , bir fiyatın hesaplanamama durumunu not edin.

Geliştiricilere yanıt türlerini ve hata kodlarını anlatmanın daha iyi bir yolu, aşağıdaki XML açıklamalarını ve veri açıklamalarını kullanmaktır. Swashbuckle ve Swagger araçları, beklenen HTTP yanıt kodlarının OpenAPI açıklamasını net bir şekilde oluşturmak için bu değerleri kullanır.

Ayrıca HTTP fiil filtresi oluşturucuyu özelliğini içerecek şekilde güncelleştirin Name ve OpenAPI operationId değerini ekleyin.

  1. PriceFrameController.cs dosyasına aşağıdaki using deyimini ekleyin.

    using Microsoft.AspNetCore.Http;

  2. PriceFrameController.cs dosyasında değerini aşağıdaki kod ve açıklamayla değiştirinGetPrice.

    /// <summary>
/// Returns the price of a frame based on its dimensions.
/// </summary>
/// <param name="Height">The height of the frame.</param>
/// <param name="Width">The width of the frame.</param>
/// <returns>The price, in dollars, of the picture frame.</returns>
/// <remarks>
/// Sample request:
///
///     Get /api/priceframe/5/10
///
/// </remarks>
/// <response code="200">Returns the cost of the frame in dollars.</response>
/// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response>
[HttpGet("{Height}/{Width}", Name=nameof(GetPrice))]
[Produces("text/plain")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> GetPrice(string Height, string Width)
{
    string result;
    result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
    if (result == "not valid")
    {
        return BadRequest(result);
    }
    else
    {
        return Ok($"The cost of a {Height}x{Width} frame is ${result}");
    }
}

    Bu kod güncelleştirmesi aşağıdaki değişiklikleri yapar:

    • Yöntem, BadRequest() ve Ok() yöntemlerini kullanarak bir BadRequest (400) ve Tamam durumu oluşturur ve dize sonucunu yanıta iletir.
    • XML açıklamaları, bu yöntemin döndürebileceği her durum kodunu açıklar.
    • HttpGet özniteliği, OpenAPI operationId parametresini yaymak için bir Name özellik içerir.
    • ProducesResponseType öznitelikleri, eylemin döndürebileceği farklı yanıtları listeler. Bu öznitelikler yukarıda anlatılan XML açıklamalarıyla birleştirilir ve oluşturulan Swagger belgesindeki yanıtlar için makul açıklamalar eklenir

  3. Aşağıdaki komutla web API'sini yeniden derleyin:

    dotnet build

  4. ASP.NET uygulamasını aşağıdaki komutla çalıştırın:

    dotnet run

  5. konumunda Swagger kullanıcı arabirimine yeniden http://localhost:5000/swaggerbakın ve bu ek açıklamalar tarafından sağlanan eklenen bilgileri inceleyin. API’nizin son Swagger UI’ı aşağıdaki resimde görüntülenir.

    Swagger UI with more documentation from XML comments for our API.

Bu alıştırmada, bir geliştiricinin API'niz hakkında aldığı bilgileri zenginleştirerek kullanımı çok daha kolay hale getirdiniz.