Bagikan melalui

Hasilkan dokumen OpenAPI

  • Artikel

Paket ini Microsoft.AspNetCore.OpenApi menyediakan dukungan bawaan untuk pembuatan dokumen OpenAPI di ASP.NET Core. Paket ini menyediakan fitur-fitur berikut:

  • Dukungan untuk menghasilkan dokumen OpenAPI pada waktu proses dan mengaksesnya melalui titik akhir di aplikasi.
  • Dukungan untuk API "transformer" yang memungkinkan modifikasi dokumen yang dihasilkan.
  • Dukungan untuk menghasilkan beberapa dokumen OpenAPI dari satu aplikasi.
  • Manfaatkan dukungan skema JSON yang disediakan oleh System.Text.Json.
  • Kompatibel dengan AoT asli.

Penginstalan paket

Pasang paket Microsoft.AspNetCore.OpenApi:

Jalankan perintah berikut dari Konsol Manajer Paket:

Install-Package Microsoft.AspNetCore.OpenApi

Mengonfigurasi pembuatan dokumen OpenAPI

Kode berikut:

  • Menambahkan layanan OpenAPI menggunakan metode ekstensi AddOpenApi pada kumpulan layanan pembuat aplikasi.
  • Memetakan titik akhir untuk melihat dokumen OpenAPI dalam format JSON dengan metode ekstensi MapOpenApi pada aplikasi.
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Luncurkan aplikasi dan navigasi ke https://localhost:<port>/openapi/v1.json untuk melihat dokumen OpenAPI yang dihasilkan.

Opsi untuk Menyesuaikan pembuatan dokumen OpenAPI

Bagian berikut menunjukkan cara menyesuaikan pembuatan dokumen OpenAPI.

Mengkustomisasi nama dokumen OpenAPI

Setiap dokumen OpenAPI dalam aplikasi memiliki nama yang unik. Nama dokumen default yang terdaftar adalah v1.

builder.Services.AddOpenApi(); // Document name is v1

Nama dokumen dapat dimodifikasi dengan meneruskan nama sebagai parameter ke AddOpenApi panggilan.

builder.Services.AddOpenApi("internal"); // Document name is internal

Nama dokumen muncul di beberapa tempat dalam implementasi OpenAPI.

Saat mengambil dokumen OpenAPI yang dihasilkan, nama dokumen disediakan sebagai documentName argumen parameter dalam permintaan. Permintaan berikut menyelesaikan dokumen v1 dan internal.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Mengkustomisasi versi OpenAPI dari dokumen yang dihasilkan

Secara default, pembuatan dokumen OpenAPI membuat dokumen yang sesuai dengan v3.0 dari spesifikasi OpenAPI. Kode berikut menunjukkan cara mengubah versi default dokumen OpenAPI:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

Mengkustomisasi rute titik akhir OpenAPI

Secara default, titik akhir OpenAPI yang terdaftar melalui panggilan ke MapOpenApi akan mengekspos dokumen pada titik akhir /openapi/{documentName}.json. Kode berikut menunjukkan cara mengkustomisasi rute tempat dokumen OpenAPI terdaftar:

app.MapOpenApi("/openapi/{documentName}/openapi.json");

Dimungkinkan, tetapi tidak disarankan, untuk menghapus documentName parameter rute dari rute titik akhir. documentName Saat parameter rute dihapus dari rute titik akhir, kerangka kerja mencoba menentukan nama dokumen dari parameter kueri. Tidak menyediakan documentName dalam rute atau kueri dapat mengakibatkan perilaku yang tidak terduga.

Mengkustomisasi titik akhir OpenAPI

Karena dokumen OpenAPI disajikan melalui endpoint penangan rute, kustomisasi apa pun yang tersedia untuk endpoint minimal standar juga tersedia untuk endpoint OpenAPI.

Membatasi akses dokumen OpenAPI ke pengguna yang berwenang

Titik akhir OpenAPI tidak mengaktifkan pemeriksaan otorisasi secara default. Namun, pemeriksaan otorisasi dapat diterapkan ke dokumen OpenAPI. Dalam kode berikut, akses ke dokumen OpenAPI terbatas pada yang memiliki tester peran:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

Dokumen OpenAPI yang dihasilkan dari cache

Dokumen OpenAPI diregenerasi setiap kali permintaan ke titik akhir OpenAPI dikirim. Regenerasi memungkinkan transformator untuk menggabungkan status aplikasi dinamis ke dalam operasi mereka. Misalnya, meregenerasi permintaan dengan detail konteks HTTP. Jika berlaku, dokumen OpenAPI dapat di-cache untuk menghindari eksekusi alur pembuatan dokumen pada setiap permintaan HTTP.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi()
        .CacheOutput();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Membuat beberapa dokumen OpenAPI

Dalam beberapa skenario, sangat membantu untuk menghasilkan beberapa dokumen OpenAPI dengan konten yang berbeda dari satu aplikasi ASP.NET Core API. Skenario ini meliputi:

  • Menghasilkan dokumentasi OpenAPI untuk audiens yang berbeda, seperti API publik dan internal.
  • Membuat dokumentasi OpenAPI untuk versi API yang berbeda.
  • Menghasilkan dokumentasi OpenAPI untuk berbagai bagian aplikasi, seperti API frontend dan backend.

Untuk menghasilkan beberapa dokumen OpenAPI, panggil metode ekstensi AddOpenApi sekali untuk setiap dokumen, menentukan nama dokumen yang berbeda dalam parameter pertama setiap kali.

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Setiap pemanggilan AddOpenApi dapat menentukan sekumpulan opsinya sendiri, sehingga Anda dapat memilih untuk menggunakan kustomisasi yang sama atau berbeda untuk setiap dokumen OpenAPI.

Kerangka kerja menggunakan metode delegasi ShouldInclude dari OpenApiOptions untuk menentukan titik akhir mana yang akan disertakan dalam setiap dokumen.

Untuk setiap dokumen, metode delegasi ShouldInclude dipanggil untuk setiap titik akhir di aplikasi, meneruskan objek ApiDescription untuk titik akhir. Metode mengembalikan nilai boolean yang menunjukkan apakah titik akhir harus disertakan dalam dokumen. Objek ApiDescription:

  • berisi informasi tentang titik akhir, seperti metode HTTP, rute, dan jenis respons
  • Metadata yang dilampirkan ke titik akhir melalui atribut atau metode ekstensi.

Implementasi default delegasi ini menggunakan bidang GroupName dari ApiDescription. Delegat diatur pada titik akhir menggunakan metode ekstensi WithGroupName atau atribut EndpointGroupNameAttribute. WithGroupName atau atribut EndpointGroupName menentukan titik akhir mana yang akan disertakan dalam dokumen. Titik akhir apa pun yang belum ditetapkan nama grup disertakan dalam semua dokumen OpenAPI.

    // Include endpoints without a group name or with a group name that matches the document name
    ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName;

Anda dapat menyesuaikan metode delegasi ShouldInclude untuk menyertakan atau mengecualikan titik akhir berdasarkan kriteria apa pun yang Anda pilih.

Hasilkan dokumen OpenAPI pada waktu penyusunan

Di aplikasi web biasa, dokumen OpenAPI dihasilkan pada run-time dan dilayani melalui permintaan HTTP ke server aplikasi.

Dalam beberapa skenario, sangat membantu untuk menghasilkan dokumen OpenAPI selama langkah build aplikasi. Skenario ini meliputi:

  • Menghasilkan dokumentasi OpenAPI yang diterapkan ke dalam pengendalian sumber.
  • Menghasilkan dokumentasi OpenAPI yang digunakan untuk pengujian integrasi berbasis spesifikasi.
  • Menghasilkan dokumentasi OpenAPI yang dilayani secara statis dari server web.

Untuk menambahkan dukungan untuk membuat dokumen OpenAPI pada waktu build, instal Microsoft.Extensions.ApiDescription.Server paket:

Jalankan perintah berikut dari Konsol Manajer Paket:

Install-Package Microsoft.Extensions.ApiDescription.Server

Setelah penginstalan, paket ini:

  • Secara otomatis menghasilkan dokumen Open API yang terkait dengan aplikasi selama build.
  • Mengisi dokumen Open API di direktori output aplikasi.

Jika beberapa dokumen terdaftar, nama dokumen dan adalah , bukanv1, dan diikuti dengan nama dokumen. Misalnya, {ProjectName}_{DocumentName}.json.

dotnet build
type obj\{ProjectName}.json

Menyesuaikan generasi dokumen selama proses pembangunan

Memodifikasi direktori output file Open API yang dihasilkan

Secara default, dokumen OpenAPI yang dihasilkan akan dipancarkan ke direktori output aplikasi. Untuk mengubah lokasi file yang dipancarkan, atur jalur target di OpenApiDocumentsDirectory properti .

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
</PropertyGroup>

Nilai OpenApiDocumentsDirectory ditentukan relatif terhadap berkas proyek. Menggunakan nilai di . atas akan memancarkan dokumen OpenAPI dalam direktori yang sama dengan file proyek.

Memodifikasi nama file output

Secara default, dokumen OpenAPI yang dihasilkan akan memiliki nama yang sama dengan file proyek aplikasi. Untuk mengubah nama file keluaran, atur argumen --file-name dalam properti OpenApiGenerateDocumentsOptions.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Memilih dokumen OpenAPI yang akan dihasilkan

Beberapa aplikasi dapat dikonfigurasi untuk memancarkan beberapa dokumen OpenAPI. Beberapa dokumen OpenAPI dapat dibuat untuk versi API yang berbeda atau untuk membedakan antara API publik dan internal. Secara bawaan, pembangkit dokumen pada saat pembangunan menghasilkan file untuk semua dokumen yang dikonfigurasi dalam aplikasi. Untuk hanya memancarkan dengan satu nama dokumen, atur argumen --document-name dalam properti OpenApiGenerateDocumentsOptions.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Menyesuaikan perilaku runtime pada waktu pembuatan dokumen build-time

Fungsi pembangkitan dokumen OpenAPI selama proses build-time dengan meluncurkan aplikasi melalui titik masuk menggunakan implementasi server tiruan. Server tiruan diperlukan untuk menghasilkan dokumen OpenAPI yang akurat karena semua informasi dalam dokumen OpenAPI tidak dapat dianalisis secara statis. Karena titik masuk aplikasi dipanggil, logika apa pun dalam startup aplikasi dipanggil. Ini termasuk kode yang menyuntikkan layanan ke dalam kontainer DI atau membaca dari konfigurasi. Dalam beberapa skenario, diperlukan untuk membatasi jalur kode yang akan dijalankan ketika titik masuk aplikasi dipanggil dari pembuatan dokumen pada saat build. Skenario ini meliputi:

  • Tidak membaca dari string konfigurasi tertentu.
  • Tidak mendaftarkan layanan terkait database.

Untuk membatasi jalur kode ini agar tidak dipanggil selama proses pembuatan, jalur tersebut dapat dikondisikan di balik pemeriksaan rakitan masukan.

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
    builder.AddServiceDefaults();
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults menambahkan layanan .NET Aspire umum seperti penemuan layanan, ketahanan, pemeriksaan kesehatan, dan OpenTelemetry.

Pemangkasan dan Kompilasi AOT Asli

OpenAPI di ASP.NET Core mendukung trimming dan native AOT. Langkah-langkah berikut menciptakan dan menerbitkan aplikasi OpenAPI dengan pemangkasan dan kompilasi AOT asli:

Buat proyek ASP.NET Core Web API (Native AOT) baru.

dotnet new webapiaot

Tambahkan paket Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi

Perbarui Program.cs untuk mengaktifkan pembuatan dokumen OpenAPI.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Terbitkan aplikasi.

dotnet publish

API minimal menyediakan dukungan bawaan untuk menghasilkan informasi tentang titik akhir dalam aplikasi melalui paket Microsoft.AspNetCore.OpenApi. Mengekspos definisi OpenAPI yang dihasilkan melalui UI visual memerlukan paket pihak ketiga. Untuk informasi tentang dukungan untuk OpenAPI di API berbasis pengontrol, lihat versi .NET 9 dari artikel ini.

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 menggantikan anotasi default yang dicocokkan dan dihasilkan oleh API Explorer dengan anotasi yang dihasilkan dari paket Microsoft.AspNetCore.OpenApi.
  • menambahkan middleware Swagger.
  • 'UseSwaggerUI' mengaktifkan versi tersemat dari alat antarmuka pengguna Swagger.
  • WithName: IEndpointNameMetadata yang ada pada titik akhir digunakan untuk pembuatan tautan dan diperlakukan sebagai ID operasi dalam spesifikasi OpenAPI dari titik akhir yang diberikan.
  • WithOpenApi dijelaskan kemudian dalam artikel ini.

Microsoft.AspNetCore.OpenApi Paket NuGet

ASP.NET Core menyediakan paket Microsoft.AspNetCore.OpenApi untuk melakukan interaksi dengan spesifikasi OpenAPI pada endpoint. 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 dalam pemanggilan WithOpenApi untuk memanfaatkan konstruktor salinan.

Menambahkan anotasi OpenAPI ke titik akhir melalui WithOpenApi

Memanggil WithOpenApi pada titik akhir menambah 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");

Sebagai alternatif, daftar OpenApiTags dapat diatur pada anotasi OpenAPI melalui ekstensi WithOpenApi.

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 contoh berikut, titik akhir /skipme dikecualikan dalam proses 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:

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 menambahkan anotasi pada endpoint dengan respons berdasarkan kode status 200 dan jenis konten application/json.

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, ProducesValidationProblem, atau TypedResults.Problem dapat digunakan untuk menambahkan anotasi yang sesuai ke metadata titik akhir. Perhatikan bahwa metode ekstensi ProducesProblem dan ProducesValidationProblem tidak dapat digunakan dengan grup rute di .NET 8 dan versi sebelumnya.

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> menyatakan bahwa suatu handler rute mengembalikan beberapa jenis konkret yang menerapkan IResult, dan tipe mana pun yang menerapkan IEndpointMetadataProvider akan berkontribusi pada metadata titik akhir.

    Tipe union mengimplementasikan 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 pada saat kompilasi bahwa suatu handler rute hanya mengembalikan hasil yang sudah dinyatakan. 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 memberikan anotasi pada input yang digunakan oleh API. Input ini termasuk dalam dua kategori:

  • Parameter yang muncul di jalur URL, string kueri, header, atau cookie
  • 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, endpoint menerima objek Todo dalam isi permintaan dengan tipe konten yang diharapkan adalah application/xml.

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

Selain metode ekstensi Accepts, jenis parameter dapat menggambarkan anotasinya sendiri dengan mengimplementasikan antarmuka IEndpointParameterMetadataProvider. Misalnya, tipe berikut Todo menambahkan anotasi yang memerlukan badan permintaan dengan application/xml tipe 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 bersifat nullable atau jika properti AllowEmpty disetel pada atribut FromBody.

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

Sumber Tambahan

Aplikasi API minimal dapat menggambarkan spesifikasi OpenAPI untuk handler rute menggunakan Swashbuckle.

Untuk informasi tentang dukungan untuk OpenAPI di API berbasis pengontrol, lihat versi .NET 9 dari artikel ini.

Kode berikut adalah aplikasi ASP.NET Core yang khas dengan dukungan OpenAPI:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
                               Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
                                    $"{builder.Environment.ApplicationName} v1"));
}

app.MapGet("/swag", () => "Hello Swagger!");

app.Run();

Mengecualikan deskripsi OpenAPI

Dalam contoh berikut, titik akhir /skipme dikecualikan dalam proses pembuatan deskripsi OpenAPI.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

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

app.Run();

Menjelaskan jenis respons

Contoh berikut menggunakan jenis hasil bawaan untuk mengkustomisasi respons:

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);

Menambahkan id operasi ke OpenAPI

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

Menambahkan tag ke deskripsi OpenAPI

Kode berikut menggunakan tag pengelompokan OpenAPI:

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