Hasilkan dokumen OpenAPI
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 pada 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 -IncludePrerelease
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 -IncludePrerelease
Mengonfigurasi pembuatan dokumen OpenAPI
Kode berikut:
- Menambahkan layanan OpenAPI.
- Mengaktifkan titik akhir untuk menampilkan dokumen OpenAPI dalam format JSON.
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi();
var app = builder.Build();
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.
Menyertakan metadata OpenAPI dalam aplikasi web ASP.NET
Menyertakan metadata OpenAPI untuk titik akhir
ASP.NET mengumpulkan metadata dari titik akhir aplikasi web dan menggunakannya untuk menghasilkan dokumen OpenAPI.
Dalam aplikasi berbasis pengontrol, metadata dikumpulkan dari atribut seperti [EndpointDescription]
, , [HttpPost]
dan [Produces]
.
Dalam API minimal, metadata dapat dikumpulkan dari atribut, tetapi juga dapat diatur dengan menggunakan metode ekstensi dan strategi lain, seperti kembali TypedResults dari penangan rute.
Tabel berikut ini menyediakan gambaran umum metadata yang dikumpulkan dan strategi untuk mengaturnya.
Metadata | Atribut | Metode ekstensi | Strategi lain |
---|---|---|---|
ringkasan | [EndpointSummary] |
WithSummary | |
description | [EndpointDescription] |
WithDescription | |
tag | [Tags] |
WithTags | |
operationId | [EndpointName] |
WithName | |
parameter | [FromQuery] , , [FromRoute] [FromHeader] ,[FromForm] |
||
deskripsi parameter | [EndpointDescription] |
||
requestBody | [FromBody] |
Accepts | |
Responses to | [Produces] |
Produces, ProducesProblem | TypedResults |
Mengecualikan titik akhir | [ExcludeFromDescription] , [ApiExplorerSettings] |
ExcludeFromDescription |
ASP.NET Core tidak mengumpulkan metadata dari komentar dokumen XML.
Bagian berikut menunjukkan cara menyertakan metadata dalam aplikasi untuk menyesuaikan dokumen OpenAPI yang dihasilkan.
Ringkasan dan deskripsi
Ringkasan dan deskripsi titik akhir dapat diatur menggunakan [EndpointSummary]
atribut dan [EndpointDescription]
, atau dalam API minimal, menggunakan WithSummary metode ekstensi dan WithDescription .
Sampel berikut menunjukkan berbagai strategi untuk mengatur ringkasan dan deskripsi.
Perhatikan bahwa atribut ditempatkan pada metode delegasi dan bukan pada aplikasi. Metode MapGet.
app.MapGet("/extension-methods", () => "Hello world!")
.WithSummary("This is a summary.")
.WithDescription("This is a description.");
app.MapGet("/attributes",
[EndpointSummary("This is a summary.")]
[EndpointDescription("This is a description.")]
() => "Hello world!");
tag
OpenAPI mendukung penentuan tag pada setiap titik akhir sebagai bentuk kategorisasi.
Dalam API minimal, tag dapat diatur menggunakan [Tags]
atribut atau WithTags metode ekstensi.
Sampel berikut menunjukkan berbagai strategi untuk mengatur tag.
app.MapGet("/extension-methods", () => "Hello world!")
.WithTags("todos", "projects");
app.MapGet("/attributes",
[Tags("todos", "projects")]
() => "Hello world!");
operationId
OpenAPI mendukung operationId pada setiap titik akhir sebagai pengidentifikasi atau nama unik untuk operasi.
Dalam API minimal, operationId dapat diatur menggunakan [EndpointName]
atribut atau WithName metode ekstensi.
Sampel berikut menunjukkan berbagai strategi untuk mengatur operationId.
app.MapGet("/extension-methods", () => "Hello world!")
.WithName("FromExtensionMethods");
app.MapGet("/attributes",
[EndpointName("FromAttributes")]
() => "Hello world!");
parameter
OpenAPI mendukung jalur anotasi, string kueri, header, dan cookie parameter yang digunakan oleh API.
Kerangka kerja menyimpulkan jenis untuk parameter permintaan secara otomatis berdasarkan tanda tangan handler rute.
Atribut [EndpointDescription]
dapat digunakan untuk memberikan deskripsi untuk parameter.
Sampel berikut menunjukkan cara mengatur deskripsi untuk parameter.
app.MapGet("/attributes",
([Description("This is a description.")] string name) => "Hello world!");
Menjelaskan isi permintaan
Bidang requestBody
di OpenAPI menjelaskan isi permintaan yang dapat dikirim klien API ke server, termasuk jenis konten yang didukung dan skema untuk konten isi.
Ketika metode handler titik akhir menerima parameter yang terikat dari isi permintaan, ASP.NET Core menghasilkan yang sesuai requestBody
untuk operasi dalam dokumen OpenAPI. Metadata untuk isi permintaan juga dapat ditentukan menggunakan atribut atau metode ekstensi. Metadata tambahan dapat diatur dengan transformator dokumen atau transformator operasi.
Jika titik akhir tidak menentukan parameter apa pun yang terikat ke isi permintaan, tetapi sebaliknya menggunakan isi permintaan dari HttpContext secara langsung, ASP.NET Core menyediakan mekanisme untuk menentukan metadata isi permintaan. Ini adalah skenario umum untuk titik akhir yang memproses isi permintaan sebagai aliran.
Beberapa metadata isi permintaan dapat ditentukan dari FromBody
parameter atau FromForm
metode handler rute.
Deskripsi untuk isi permintaan dapat diatur dengan [Description]
atribut pada parameter dengan FromBody
atau FromForm
.
FromBody
Jika parameter tidak dapat diubah ke null dan EmptyBodyBehavior tidak diatur ke Allow dalam FromBody
atribut, isi permintaan diperlukan dan required
bidang requestBody
diatur ke true
dalam dokumen OpenAPI yang dihasilkan.
Badan formulir selalu diperlukan dan telah required
diatur ke true
.
Gunakan transformator dokumen atau transformator operasi untuk mengatur example
bidang , , examples
atau encoding
, atau untuk menambahkan ekstensi spesifikasi untuk isi permintaan dalam dokumen OpenAPI yang dihasilkan.
Mekanisme lain untuk mengatur metadata isi permintaan bergantung pada jenis aplikasi yang sedang dikembangkan dan dijelaskan di bagian berikut.
Jenis konten untuk isi permintaan dalam dokumen OpenAPI yang dihasilkan ditentukan dari jenis parameter yang terikat ke isi permintaan atau ditentukan dengan Accepts metode ekstensi.
Secara default, jenis FromBody
konten parameter akan menjadi application/json
dan jenis konten untuk FromForm
parameter adalah multipart/form-data
atau application/x-www-form-urlencoded
.
Dukungan untuk jenis konten default ini dibangun ke API Minimal, dan jenis konten lainnya dapat ditangani dengan menggunakan pengikatan kustom. Lihat topik Pengikatan kustom dokumentasi API Minimal untuk informasi selengkapnya.
Ada beberapa cara untuk menentukan jenis konten yang berbeda untuk isi permintaan.
Jika jenis FromBody
parameter mengimplementasikan IEndpointParameterMetadataProvider, ASP.NET Core menggunakan antarmuka ini untuk menentukan jenis konten dalam isi permintaan.
Kerangka kerja menggunakan PopulateMetadata metode antarmuka ini untuk mengatur jenis konten dan jenis konten isi isi permintaan. Misalnya, Todo
kelas yang menerima salah satu application/xml
atau text/xml
jenis konten dapat digunakan IEndpointParameterMetadataProvider untuk memberikan informasi ini ke kerangka kerja.
public class Todo : IEndpointParameterMetadataProvider
{
public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
{
builder.Metadata.Add(new AcceptsMetadata(["application/xml", "text/xml"], typeof(Todo)));
}
}
Metode Accepts ekstensi juga dapat digunakan untuk menentukan jenis konten isi permintaan.
Dalam contoh berikut, titik akhir menerima Todo
objek dalam isi permintaan dengan tipe konten yang diharapkan dari application/xml
.
app.MapPut("/todos/{id}", (int id, Todo todo) => ...)
.Accepts<Todo>("application/xml");
Karena application/xml
bukan jenis konten bawaan Todo
, kelas harus mengimplementasikan IBindableFromHttpContext<TSelf> antarmuka untuk menyediakan pengikatan kustom untuk isi permintaan. Contohnya:
public class Todo : IBindableFromHttpContext<Todo>
{
public static async ValueTask<Todo?> BindAsync(HttpContext context, ParameterInfo parameter)
{
var xmlDoc = await XDocument.LoadAsync(context.Request.Body, LoadOptions.None, context.RequestAborted);
var serializer = new XmlSerializer(typeof(Todo));
return (Todo?)serializer.Deserialize(xmlDoc.CreateReader());
}
Jika titik akhir tidak menentukan parameter apa pun yang terikat ke isi permintaan, gunakan Accepts metode ekstensi untuk menentukan jenis konten yang diterima titik akhir.
Jika Anda menentukan <AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Accepts%2A> beberapa kali, hanya metadata dari yang terakhir yang digunakan -- metadata tersebut tidak digabungkan.
Menjelaskan jenis respons
OpenAPI mendukung memberikan deskripsi respons yang dikembalikan dari API. ASP.NET Core menyediakan beberapa strategi untuk mengatur metadata respons titik akhir. Metadata respons yang dapat diatur mencakup kode status, jenis isi respons, dan jenis konten respons. Respons di OpenAPI mungkin memiliki metadata tambahan, seperti deskripsi, header, tautan, dan contoh. Metadata tambahan ini dapat diatur dengan transformator dokumen atau transformator operasi.
Mekanisme khusus untuk mengatur metadata respons bergantung pada jenis aplikasi yang sedang dikembangkan.
Di aplikasi API Minimal, ASP.NET Core dapat mengekstrak metadata respons yang ditambahkan oleh metode ekstensi pada titik akhir, atribut pada handler rute, dan jenis pengembalian penangan rute.
- Metode Produces ekstensi dapat digunakan pada titik akhir untuk menentukan kode status, jenis isi respons, dan jenis konten respons dari titik akhir.
- Atribut
[ProducesResponseType]
atau ProducesResponseTypeAttribute<T> dapat digunakan untuk menentukan jenis isi respons. - Handler rute dapat digunakan untuk mengembalikan jenis yang mengimplementasikan IEndpointMetadataProvider untuk menentukan jenis dan jenis konten isi respons.
- Metode ProducesProblem ekstensi pada titik akhir dapat digunakan untuk menentukan kode status dan jenis konten respons kesalahan.
Perhatikan bahwa Produces metode ekstensi dan ProducesProblem didukung pada dan RouteHandlerBuilder pada RouteGroupBuilder. Ini memungkinkan, misalnya, serangkaian respons kesalahan umum yang akan ditentukan untuk semua operasi dalam grup.
Ketika tidak ditentukan oleh salah satu strategi sebelumnya, :
- Kode status untuk respons default ke 200.
- Skema untuk isi respons dapat disimpulkan dari jenis pengembalian implisit atau eksplisit dari metode titik akhir, misalnya, dari
T
dalam Task<TResult>; jika tidak, itu dianggap tidak ditentukan. - Jenis konten untuk isi respons yang ditentukan atau disimpulkan adalah "application/json".
Di API Minimal, Produces metode ekstensi dan [ProducesResponseType]
atribut hanya mengatur metadata respons untuk titik akhir. Mereka tidak mengubah atau membatasi perilaku titik akhir, yang dapat mengembalikan kode status atau jenis isi respons yang berbeda dari yang ditentukan oleh metadata, dan jenis konten ditentukan oleh jenis pengembalian metode penangan rute, terlepas dari jenis konten apa pun yang ditentukan dalam atribut atau metode ekstensi.
Metode Produces ekstensi dapat menentukan jenis respons titik akhir, dengan kode status default 200 dan jenis application/json
konten default . Contoh berikut mengilustrasikan langkah-langkah ini:
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.Produces<IList<Todo>>();
[ProducesResponseType]
dapat digunakan untuk menambahkan metadata respons ke titik akhir. Perhatikan bahwa atribut diterapkan ke metode handler rute, bukan pemanggilan metode untuk membuat rute, seperti yang ditunjukkan dalam contoh berikut:
app.MapGet("/todos",
[ProducesResponseType<List<Todo>>(200)]
async (TodoDb db) => await db.Todos.ToListAsync());
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);
});
Hanya kembalikan jenis yang mengimplementasikan IEndpointMetadataProvider buat responses
entri di dokumen OpenAPI. Berikut ini adalah daftar parsial dari beberapa metode pembantu TypedResults yang menghasilkan responses
entri:
Metode pembantu TypedResults | status code |
---|---|
Ok() | 200 |
Dibuat() | 201 |
CreatedAtRoute() | 201 |
Diterima() | 202 |
AcceptedAtRoute() | 202 |
NoContent() | 204 |
BadRequest() | 400 |
ValidationProblem() | 400 |
NotFound() | 404 |
Konflik() | 409 |
UnprocessableEntity() | 422 |
Semua metode ini kecuali NoContent
memiliki kelebihan beban umum yang menentukan jenis isi respons.
Kelas dapat diimplementasikan untuk mengatur metadata titik akhir dan mengembalikannya dari handler rute.
Mengatur respons untuk ProblemDetails
Saat mengatur jenis respons untuk titik akhir yang mungkin mengembalikan respons ProblemDetails, berikut ini dapat digunakan untuk menambahkan metadata respons yang sesuai untuk titik akhir:
- ProducesProblem
- ProducesValidationProblem metode ekstensi.
- TypedResults dengan kode status dalam rentang (400-499).
Untuk informasi selengkapnya tentang cara mengonfigurasi aplikasi API Minimal untuk mengembalikan respons ProblemDetails, lihat Menangani kesalahan dalam API minimal.
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,TResult3,TResult4,TResult5,TResult6> 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 beberapaIResult
jenis 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.
Mengecualikan titik akhir dari dokumen yang dihasilkan
Secara default, semua titik akhir yang ditentukan dalam aplikasi didokumenkan dalam file OpenAPI yang dihasilkan, tetapi titik akhir dapat dikecualikan dari dokumen menggunakan atribut atau metode ekstensi.
Mekanisme untuk menentukan titik akhir yang harus dikecualikan tergantung pada jenis aplikasi yang sedang dikembangkan.
API minimal mendukung dua strategi untuk mengecualikan titik akhir tertentu dari dokumen OpenAPI:
- ExcludeFromDescription metode ekstensi
- atribut
[ExcludeFromDescription]
Sampel berikut menunjukkan berbagai strategi untuk mengecualikan titik akhir tertentu dari dokumen OpenAPI yang dihasilkan.
app.MapGet("/extension-method", () => "Hello world!")
.ExcludeFromDescription();
app.MapGet("/attributes",
[ExcludeFromDescription]
() => "Hello world!");
Termasuk metadata OpenAPI untuk jenis data
Kelas atau rekaman C# yang digunakan dalam badan permintaan atau respons diwakili sebagai skema dalam dokumen OpenAPI yang dihasilkan. Secara default, hanya properti publik yang diwakili dalam skema, tetapi ada JsonSerializerOptions juga untuk membuat properti skema untuk bidang.
PropertyNamingPolicy Ketika diatur ke camel-case (ini adalah default dalam aplikasi web ASP.NET), nama properti dalam skema adalah bentuk camel-case dari nama properti kelas atau rekaman.
[JsonPropertyName]
dapat digunakan pada properti individual untuk menentukan nama properti dalam skema.
jenis dan format
Pustaka Skema JSON memetakan jenis C# standar ke OpenAPI type
dan format
sebagai berikut:
Jenis C# | OpenAPI type |
OpenAPI format |
---|---|---|
int | Integer | int32 |
long | Integer | int64 |
pendek | Integer | int16 |
byte | Integer | uint8 |
float | number | float |
ganda | number | ganda |
desimal | number | ganda |
bool | Boolean | |
string | string | |
char | string | char |
byte[] | string | byte |
DateTimeOffset | string | tanggal-waktu |
DateOnly | string | date |
TimeOnly | string | waktu |
Uri | string | uri |
Guid | string | uuid |
object | Dihilangkan | |
dinamis | Dihilangkan |
Perhatikan bahwa objek dan jenis dinamis tidak memiliki jenis yang ditentukan dalam OpenAPI karena ini dapat berisi data dari jenis apa pun, termasuk jenis primitif seperti int atau string.
type
dan format
juga dapat diatur dengan Transformer Skema. Misalnya, Anda mungkin ingin format
jenis desimal menjadi decimal
bukan double
.
Menggunakan atribut untuk menambahkan metadata
ASP.NET menggunakan metadata dari atribut pada kelas atau properti rekaman untuk mengatur metadata pada properti terkait dari skema yang dihasilkan.
Tabel berikut ini meringkas atribut dari System.ComponentModel
namespace layanan yang menyediakan metadata untuk skema yang dihasilkan:
Atribut | Deskripsi |
---|---|
[Description] |
description Mengatur properti dalam skema. |
[Required] |
Menandai properti sebagai required dalam skema. |
[DefaultValue] |
default Mengatur nilai properti dalam skema. |
[Range] |
Mengatur nilai minimum dan maximum bilangan bulat atau angka. |
[MinLength] |
minLength Mengatur string. |
[MaxLength] |
maxLength Mengatur string. |
[RegularExpression] |
pattern Mengatur string. |
Perhatikan bahwa dalam aplikasi berbasis pengontrol, atribut ini menambahkan filter ke operasi untuk memvalidasi bahwa data masuk memenuhi batasan. Dalam API Minimal, atribut ini mengatur metadata dalam skema yang dihasilkan tetapi validasi harus dilakukan secara eksplisit melalui filter titik akhir, dalam logika handler rute, atau melalui paket pihak ketiga.
Sumber metadata lain untuk skema yang dihasilkan
wajib diisi
Properti juga dapat ditandai sebagai required
dengan pengubah yang diperlukan .
enum
Jenis enum dalam C# berbasis bilangan bulat, tetapi dapat direpresentasikan sebagai string di JSON dengan [JsonConverter]
dan JsonStringEnumConverter. Ketika jenis enum direpresentasikan sebagai string di JSON, skema yang dihasilkan akan memiliki enum
properti dengan nilai string enum.
Jenis enum tanpa [JsonConverter]
akan didefinisikan sebagai type: integer
dalam skema yang dihasilkan.
Catatan: [AllowedValues]
tidak mengatur enum
nilai properti.
nullable
Properti yang didefinisikan sebagai nilai nullable atau jenis referensi dalam nullable: true
skema yang dihasilkan. Ini konsisten dengan perilaku System.Text.Json default deserializer, yang menerima null
sebagai nilai yang valid untuk properti nullable.
additionalProperties
Skema dihasilkan tanpa additionalProperties
pernyataan secara default, yang menyiratkan default true
. Ini konsisten dengan perilaku System.Text.Json default deserializer, yang secara diam-diam mengabaikan properti tambahan dalam objek JSON.
Jika properti tambahan skema hanya boleh memiliki nilai dari jenis tertentu, tentukan properti atau kelas sebagai Dictionary<string, type>
. Jenis kunci untuk kamus harus string
. Ini menghasilkan skema dengan additionalProperties
menentukan skema untuk "jenis" sebagai jenis nilai yang diperlukan.
Metadata untuk jenis polimorfik
[JsonPolymorphic]
Gunakan atribut dan [JsonDerivedType]
pada kelas induk untuk menentukan bidang diskriminator dan subjenis untuk jenis polimorfik.
menambahkan [JsonDerivedType]
bidang diskriminator ke skema untuk setiap subkelas, dengan enum yang menentukan nilai diskriminator tertentu untuk subkelas. Atribut ini juga memodifikasi konstruktor dari setiap kelas turunan untuk mengatur nilai diskriminator.
Kelas abstrak dengan [JsonPolymorphic]
atribut memiliki discriminator
bidang dalam skema, tetapi kelas konkret dengan [JsonPolymorphic]
atribut tidak memiliki discriminator
bidang. OpenAPI mengharuskan properti diskriminator menjadi properti yang diperlukan dalam skema, tetapi karena properti diskriminator tidak didefinisikan dalam kelas dasar beton, skema tidak dapat menyertakan discriminator
bidang.
Menambahkan metadata dengan transformator skema
Transformator skema dapat digunakan untuk mengambil alih metadata default atau menambahkan metadata tambahan, seperti example
nilai, ke skema yang dihasilkan. Lihat Menggunakan transformator skema untuk informasi selengkapnya.
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 v1
dokumen 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 terdaftar melalui panggilan untuk MapOpenApi mengekspos dokumen di /openapi/{documentName}.json
titik akhir. 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 menyelesaikan 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 titik akhir handler rute, kustomisasi apa pun yang tersedia untuk titik akhir minimal standar tersedia untuk titik akhir 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 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();
app.MapOpenApi()
.CacheOutput();
app.MapGet("/", () => "Hello world!");
app.Run();
Transformator dokumen OpenAPI
Bagian ini menunjukkan cara menyesuaikan dokumen OpenAPI dengan transformator.
Menyesuaikan dokumen OpenAPI dengan transformator
Transformer menyediakan API untuk memodifikasi dokumen OpenAPI dengan kustomisasi yang ditentukan pengguna. Transformer berguna untuk skenario seperti:
- Menambahkan parameter ke semua operasi dalam dokumen.
- Memodifikasi deskripsi untuk parameter atau operasi.
- Menambahkan informasi tingkat atas ke dokumen OpenAPI.
Transformer termasuk dalam tiga kategori:
- Transformator dokumen memiliki akses ke seluruh dokumen OpenAPI. Ini dapat digunakan untuk membuat modifikasi global pada dokumen.
- Transformator operasi berlaku untuk setiap operasi individu. Setiap operasi individu adalah kombinasi jalur dan metode HTTP. Ini dapat digunakan untuk mengubah parameter atau respons pada titik akhir.
- Transformator skema berlaku untuk setiap skema dalam dokumen. Ini dapat digunakan untuk memodifikasi skema badan permintaan atau respons, atau skema berlapis apa pun.
Transformer dapat didaftarkan ke dokumen dengan memanggil AddDocumentTransformer metode pada OpenApiOptions objek. Cuplikan berikut menunjukkan berbagai cara untuk mendaftarkan transformator ke dokumen:
- Daftarkan transformator dokumen menggunakan delegasi.
- Daftarkan transformator dokumen menggunakan instans IOpenApiDocumentTransformer.
- Daftarkan transformator dokumen menggunakan yang diaktifkan IOpenApiDocumentTransformerDI .
- Daftarkan transformator operasi menggunakan delegasi.
- Daftarkan transformator operasi menggunakan instans IOpenApiOperationTransformer.
- Daftarkan transformator operasi menggunakan yang diaktifkan IOpenApiOperationTransformerDI .
- Daftarkan transformator skema menggunakan delegasi.
- Daftarkan transformator skema menggunakan instans IOpenApiSchemaTransformer.
- Daftarkan transformator skema menggunakan yang diaktifkan IOpenApiSchemaTransformerDI .
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
options.AddDocumentTransformer(new MyDocumentTransformer());
options.AddDocumentTransformer<MyDocumentTransformer>();
options.AddOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
options.AddOperationTransformer(new MyOperationTransformer());
options.AddOperationTransformer<MyOperationTransformer>();
options.AddSchemaTransformer((schema, context, cancellationToken)
=> Task.CompletedTask);
options.AddSchemaTransformer(new MySchemaTransformer());
options.AddSchemaTransformer<MySchemaTransformer>();
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Urutan eksekusi untuk transformator
Transformer dijalankan dalam urutan first-in first-out berdasarkan pendaftaran. Dalam cuplikan berikut, transformator dokumen memiliki akses ke modifikasi yang dibuat oleh transformator operasi:
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
options.AddDocumentTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Menggunakan transformator dokumen
Transformator dokumen memiliki akses ke objek konteks yang mencakup:
- Nama dokumen yang sedang dimodifikasi.
- Yang terkait dengan dokumen tersebut ApiDescriptionGroups .
- yang IServiceProvider digunakan dalam pembuatan dokumen.
Transformator dokumen juga dapat mengubah dokumen OpenAPI yang dihasilkan. Contoh berikut menunjukkan transformator dokumen yang menambahkan beberapa informasi tentang API ke dokumen OpenAPI.
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((document, context, cancellationToken) =>
{
document.Info = new()
{
Title = "Checkout API",
Version = "v1",
Description = "API for processing checkouts from cart."
};
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Transformer dokumen yang diaktifkan layanan dapat menggunakan instans dari DI untuk memodifikasi aplikasi. Sampel berikut menunjukkan transformator dokumen yang menggunakan IAuthenticationSchemeProvider layanan dari lapisan autentikasi. Ini memeriksa apakah ada skema terkait pembawa JWT yang terdaftar di aplikasi dan menambahkannya ke tingkat atas dokumen OpenAPI:
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.AddOpenApi(options =>
{
options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
}
}
}
Transformator dokumen unik untuk instans dokumen yang terkait dengannya. Dalam contoh berikut, transformator:
- Mendaftarkan persyaratan terkait autentikasi ke
internal
dokumen. - Membiarkan dokumen tidak dimodifikasi
public
.
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.AddOpenApi("internal", options =>
{
options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
builder.Services.AddOpenApi("public");
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/world", () => "Hello world!")
.WithGroupName("internal");
app.MapGet("/", () => "Hello universe!")
.WithGroupName("public");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
// Add the security scheme at the document level
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
// Apply it as a requirement for all operations
foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
{
operation.Value.Security.Add(new OpenApiSecurityRequirement
{
[new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
});
}
}
}
}
Menggunakan transformator operasi
Operasi adalah kombinasi unik jalur dan metode HTTP dalam dokumen OpenAPI. Transformer operasi sangat membantu ketika modifikasi:
- Harus dibuat untuk setiap titik akhir dalam aplikasi, atau
- Diterapkan secara kondisional ke rute tertentu.
Transformer operasi memiliki akses ke objek konteks yang berisi:
- Nama dokumen tempat operasi berada.
- Yang ApiDescription terkait dengan operasi.
- yang IServiceProvider digunakan dalam pembuatan dokumen.
Misalnya, transformator operasi berikut menambahkan 500
sebagai kode status respons yang didukung oleh semua operasi dalam dokumen.
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.AddOpenApi(options =>
{
options.AddOperationTransformer((operation, context, cancellationToken) =>
{
operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Menggunakan transformator skema
Skema adalah model data yang digunakan dalam isi permintaan dan respons dalam dokumen OpenAPI. Transformator skema berguna saat modifikasi:
- Harus dibuat untuk setiap skema dalam dokumen, atau
- Diterapkan secara kondisional ke skema tertentu.
Transformer skema memiliki akses ke objek konteks yang berisi:
- Nama dokumen tempat skema berada.
- Informasi jenis JSON yang terkait dengan skema target.
- yang IServiceProvider digunakan dalam pembuatan dokumen.
Misalnya, transformator skema berikut mengatur format
jenis desimal ke decimal
alih-alih double
:
using Microsoft.AspNetCore.OpenApi;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options => {
// Schema transformer to set the format of decimal to 'decimal'
options.AddSchemaTransformer((schema, context, cancellationToken) =>
{
if (context.JsonTypeInfo.Type == typeof(decimal))
{
schema.Format = "decimal";
}
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => new Body { Amount = 1.1m });
app.Run();
public class Body {
public decimal Amount { get; set; }
}
Sumber Daya Tambahan:
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. 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
mengambil alih pencocokan, anotasi default yang dihasilkan oleh API Explorer dengan anotasi yang dihasilkan dariMicrosoft.AspNetCore.OpenApi
paket. UseSwagger
menambahkan 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 akhirProducesResponseType
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, ProducesValidationProblem, atau TypedResults.Problem
dapat digunakan untuk menambahkan anotasi yang sesuai ke metadata titik akhir. Perhatikan bahwa ProducesProblem
metode ekstensi dan ProducesValidationProblem
tidak dapat digunakan dengan grup rute di .NET 8 dan yang lebih lama.
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 danTypedResults
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 beberapaIResult
jenis beton yang menerapkan, dan salah satu jenis yang menerapkanIEndpointMetadataProvider
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 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, 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 denganmultipart/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 padaFromBody
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
Sumber Tambahan
Aplikasi API minimal dapat menjelaskan 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 sampel berikut, /skipme
titik akhir dikecualikan dari 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");
ASP.NET Core