Dukungan OpenAPI dalam aplikasi API minimal

Spesifikasi OpenAPI adalah standar bahasa-agnostik pemrograman untuk mendokumen API HTTP. Standar ini didukung dalam API minimal melalui kombinasi API bawaan dan pustaka sumber terbuka. Ada tiga aspek utama untuk integrasi OpenAPI dalam aplikasi:

• Menghasilkan informasi tentang titik akhir di aplikasi.
• Mengumpulkan informasi ke dalam format yang cocok dengan skema OpenAPI.
• Mengekspos skema OpenAPI yang dihasilkan melalui UI visual atau file berseri.

API minimal menyediakan dukungan bawaan untuk menghasilkan informasi tentang titik akhir dalam aplikasi melalui Microsoft.AspNetCore.OpenApi paket. Mengekspos definisi OpenAPI yang dihasilkan melalui UI visual memerlukan paket pihak ketiga.

Kode berikut dihasilkan oleh templat API web minimal ASP.NET Core dan menggunakan OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Dalam kode yang disorot sebelumnya:

• Microsoft.AspNetCore.OpenApi dijelaskan di bagian berikutnya.
• AddEndpointsApiExplorer : Mengonfigurasi aplikasi untuk menggunakan API Explorer untuk menemukan dan menjelaskan titik akhir dengan anotasi default. WithOpenApi mengambil alih pencocokan, anotasi default yang dihasilkan oleh API Explorer dengan anotasi yang dihasilkan dari Microsoft.AspNetCore.OpenApi paket.
• UseSwaggermenambahkan middleware Swagger.
• 'UseSwaggerUI' memungkinkan versi alat antarmuka pengguna Swagger yang disematkan.
• WithNameIEndpointNameMetadata: Pada titik akhir digunakan untuk pembuatan tautan dan diperlakukan sebagai ID operasi dalam spesifikasi OpenAPI titik akhir yang diberikan.
• WithOpenApi dijelaskan kemudian dalam artikel ini.

Microsoft.AspNetCore.OpenApi Paket NuGet

ASP.NET Core menyediakan Microsoft.AspNetCore.OpenApi paket untuk berinteraksi dengan spesifikasi OpenAPI untuk titik akhir. Paket bertindak sebagai tautan antara model OpenAPI yang ditentukan dalam Microsoft.AspNetCore.OpenApi paket dan titik akhir yang ditentukan dalam API Minimal. Paket ini menyediakan API yang memeriksa parameter, respons, dan metadata titik akhir untuk membuat jenis anotasi OpenAPI yang digunakan untuk menjelaskan titik akhir.

Microsoft.AspNetCore.OpenApi ditambahkan sebagai PackageReference ke file proyek:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Saat menggunakan Swashbuckle.AspNetCore dengan Microsoft.AspNetCore.OpenApi, Swashbuckle.AspNetCore 6.4.0 atau yang lebih baru harus digunakan. Microsoft.OpenApi 1.4.3 atau yang lebih baru harus digunakan untuk memanfaatkan konstruktor salinan dalam WithOpenApi pemanggilan.

Menambahkan anotasi OpenAPI ke titik akhir melalui WithOpenApi

WithOpenApi Panggilan pada titik akhir ditambahkan ke metadata titik akhir. Metadata ini dapat berupa:

• Digunakan dalam paket pihak ketiga seperti Swashbuckle.AspNetCore.
• Ditampilkan di antarmuka pengguna Swagger atau di YAML atau JSON yang dihasilkan untuk menentukan API.

app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();

Mengubah anotasi OpenAPI di WithOpenApi

Metode WithOpenApi ini menerima fungsi yang dapat digunakan untuk memodifikasi anotasi OpenAPI. Misalnya, dalam kode berikut, deskripsi ditambahkan ke parameter pertama titik akhir:

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

Menambahkan ID operasi ke OpenAPI

ID operasi digunakan untuk mengidentifikasi titik akhir tertentu secara unik di OpenAPI. Metode WithName ekstensi dapat digunakan untuk mengatur ID operasi yang digunakan untuk metode .

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Atau, OperationId properti dapat diatur langsung pada anotasi OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

Menambahkan tag ke deskripsi OpenAPI

OpenAPI mendukung penggunaan objek tag untuk mengategorikan operasi. Tag ini biasanya digunakan untuk mengelompokkan operasi di antarmuka pengguna Swagger. Tag ini dapat ditambahkan ke operasi dengan memanggil metode ekstensi WithTags pada titik akhir dengan tag yang diinginkan.

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

Atau, daftar OpenApiTags dapat diatur pada anotasi OpenAPI melalui WithOpenApi metode ekstensi.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

Menambahkan ringkasan atau deskripsi titik akhir

Ringkasan dan deskripsi titik akhir dapat ditambahkan dengan memanggil WithOpenApi metode ekstensi. Dalam kode berikut, ringkasan diatur langsung pada anotasi OpenAPI.

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

Mengecualikan deskripsi OpenAPI

Dalam sampel berikut, /skipme titik akhir dikecualikan dari pembuatan deskripsi OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Menandai API sebagai usang

Untuk menandai titik akhir sebagai usang, atur Deprecated properti pada anotasi OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

Menjelaskan jenis respons

OpenAPI mendukung memberikan deskripsi respons yang dikembalikan dari API. API minimal mendukung tiga strategi untuk mengatur jenis respons titik akhir:

• Produces Melalui metode ekstensi pada titik akhir
• ProducesResponseType Melalui atribut pada handler rute
• Dengan mengembalikan TypedResults dari handler rute

Metode Produces ekstensi dapat digunakan untuk menambahkan Produces metadata ke titik akhir. Ketika tidak ada parameter yang disediakan, metode ekstensi mengisi metadata untuk jenis yang ditargetkan di bawah 200 kode status dan application/json jenis konten.

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

Menggunakan TypedResults dalam implementasi handler rute titik akhir secara otomatis menyertakan metadata jenis respons untuk titik akhir. Misalnya, kode berikut secara otomatis membuat anotasi titik akhir dengan respons di bawah 200 kode status dengan application/json jenis konten.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

Mengatur respons untuk ProblemDetails

Saat mengatur jenis respons untuk titik akhir yang dapat mengembalikan respons ProblemDetails, ProducesProblem metode ekstensi atau TypedResults.Problem dapat digunakan untuk menambahkan anotasi yang sesuai ke metadata titik akhir.

Ketika tidak ada anotasi eksplisit yang disediakan oleh salah satu strategi di atas, kerangka kerja mencoba menentukan jenis respons default dengan memeriksa tanda tangan respons. Respons default ini diisi di bawah 200 kode status dalam definisi OpenAPI.

Beberapa jenis respons

Jika titik akhir dapat mengembalikan jenis respons yang berbeda dalam skenario yang berbeda, Anda dapat menyediakan metadata dengan cara berikut:

• Produces Panggil metode ekstensi beberapa kali, seperti yang ditunjukkan dalam contoh berikut:

  app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
           await db.Todos.FindAsync(id) 
           is Todo todo
           ? Results.Ok(todo) 
           : Results.NotFound())
     .Produces<Todo>(StatusCodes.Status200OK)
     .Produces(StatusCodes.Status404NotFound);
  

• Gunakan Results<TResult1,TResult2,TResultN> dalam tanda tangan dan TypedResults di isi handler, seperti yang ditunjukkan dalam contoh berikut:

  app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
  {
      return bookList.FirstOrDefault((i) => i.Id == id) is Book book
       ? TypedResults.Ok(book)
       : TypedResults.NotFound();
  });
  

  Jenis Results<TResult1,TResult2,TResultN> gabungan menyatakan bahwa handler rute mengembalikan beberapa IResultjenis beton yang menerapkan, dan salah satu jenis yang menerapkan IEndpointMetadataProvider akan berkontribusi pada metadata titik akhir.

  Jenis serikat terapkan operator cast implisit. Operator ini memungkinkan pengkompilasi untuk secara otomatis mengonversi jenis yang ditentukan dalam argumen generik ke instans jenis gabungan. Kemampuan ini memiliki manfaat tambahan untuk memberikan pemeriksaan waktu kompilasi bahwa handler rute hanya mengembalikan hasil yang dinyatakannya. Mencoba mengembalikan jenis yang tidak dinyatakan sebagai salah satu argumen generik untuk Results<TResult1,TResult2,TResultN> menghasilkan kesalahan kompilasi.

Menjelaskan isi permintaan dan parameter

Selain menjelaskan jenis yang dikembalikan oleh titik akhir, OpenAPI juga mendukung anotasi input yang dikonsumsi oleh API. Input ini termasuk dalam dua kategori:

• Parameter yang muncul di jalur, string kueri, header, atau cookies
• Data yang dikirimkan sebagai bagian dari isi permintaan

Kerangka kerja menyimpulkan jenis untuk parameter permintaan di jalur, kueri, dan string header secara otomatis berdasarkan tanda tangan penangan rute.

Untuk menentukan jenis input yang dikirimkan sebagai isi permintaan, konfigurasikan properti dengan menggunakan Accepts metode ekstensi untuk menentukan jenis objek dan jenis konten yang diharapkan oleh penangan permintaan. Dalam contoh berikut, titik akhir menerima Todo objek dalam isi permintaan dengan tipe konten yang diharapkan dari application/xml.

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Selain Accepts metode ekstensi, Jenis parameter dapat menggambarkan anotasinya sendiri dengan mengimplementasikan IEndpointParameterMetadataProvider antarmuka. Misalnya, jenis berikut Todo menambahkan anotasi yang memerlukan isi permintaan dengan application/xml jenis konten.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

Ketika tidak ada anotasi eksplisit yang disediakan, kerangka kerja mencoba menentukan jenis permintaan default jika ada parameter isi permintaan di handler titik akhir. Inferensi menggunakan heuristik berikut untuk menghasilkan anotasi:

• Parameter isi permintaan yang dibaca dari formulir melalui [FromForm] atribut dijelaskan dengan multipart/form-data jenis konten.
• Semua parameter isi permintaan lainnya dijelaskan dengan application/json jenis konten.
• Isi permintaan diperlakukan sebagai opsional jika dapat diubah ke null atau jika AllowEmpty properti diatur pada FromBody atribut .

Mendukung penerapan versi API

API minimal mendukung penerapan versi API melalui paket Asp.Versioning.Http. Contoh konfigurasi penerapan versi dengan API minimal dapat ditemukan di repositori penerapan versi API.

ASP.NET kode sumber Core OpenAPI di GitHub

• WithOpenApi
• OpenApiGenerator

Sumber Tambahan

• Autentikasi dan otorisasi dalam API minimal