dokumentasi API web ASP.NET Core dengan Swagger/OpenAPI
Catatan
Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Penting
Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.
Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Oleh Christoph Nienaber dan Rico Suter
Swagger (OpenAPI) adalah spesifikasi agnostik bahasa untuk menjelaskan REST API. Ini memungkinkan komputer dan manusia untuk memahami kemampuan REST API tanpa akses langsung ke kode sumber. Tujuan utamanya adalah untuk:
- Minimalkan jumlah pekerjaan yang diperlukan untuk menyambungkan layanan yang dipisahkan.
- Kurangi jumlah waktu yang diperlukan untuk mendokumentasikan layanan secara akurat.
Dua implementasi OpenAPI utama untuk .NET adalah Swashbuckle dan NSwag, lihat:
OpenAPI vs. Swagger
Proyek Swagger di sumbangkan ke OpenAPI Initiative pada tahun 2015 dan sejak itu disebut sebagai OpenAPI. Kedua nama digunakan secara bergantian. Namun, "OpenAPI" mengacu pada spesifikasinya. "Swagger" mengacu pada keluarga produk sumber terbuka dan komersial dari SmartBear yang bekerja dengan Spesifikasi OpenAPI. Produk sumber terbuka berikutnya, seperti OpenAPIGenerator, juga termasuk dalam nama keluarga Swagger, meskipun tidak dirilis oleh SmartBear.
Singkatnya:
- OpenAPI adalah spesifikasi.
- Swagger adalah alat yang menggunakan spesifikasi OpenAPI. Misalnya, OpenAPIGenerator dan SwaggerUI.
Spesifikasi OpenAPI (openapi.json
)
Spesifikasi OpenAPI adalah dokumen yang menjelaskan kemampuan API Anda. Dokumen didasarkan pada XML dan anotasi atribut dalam pengontrol dan model. Ini adalah bagian inti dari alur OpenAPI dan digunakan untuk mendorong alat seperti SwaggerUI. Secara default, ini bernama openapi.json
. Berikut adalah contoh spesifikasi OpenAPI, dikurangi untuk brevity:
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Antarmuka Pengguna Swagger
UI Swagger menawarkan UI berbasis web yang menyediakan informasi tentang layanan, menggunakan spesifikasi OpenAPI yang dihasilkan. Baik Swashbuckle maupun NSwag menyertakan versi UI Swagger yang disematkan, sehingga dapat dihosting di aplikasi ASP.NET Core Anda menggunakan panggilan pendaftaran middleware. Antarmuka pengguna web terlihat seperti ini:
Setiap metode tindakan publik di pengontrol Anda dapat diuji dari UI. Pilih nama metode untuk memperluas bagian. Tambahkan parameter yang diperlukan, dan pilih Cobalah!.
Catatan
Versi UI Swagger yang digunakan untuk cuplikan layar adalah versi 2. Untuk contoh versi 3, lihat Contoh petstore.
Mengamankan titik akhir UI Swagger
Panggil MapSwagger().RequireAuthorization
untuk mengamankan titik akhir antarmuka pengguna Swagger. Contoh berikut mengamankan titik akhir swagger:
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
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.MapSwagger().RequireAuthorization();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(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(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
Dalam kode sebelumnya, /weatherforecast
titik akhir tidak memerlukan otorisasi, tetapi titik akhir Swagger melakukannya.
Curl berikut meneruskan token JWT untuk menguji titik akhir antarmuka pengguna Swagger:
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json
Untuk informasi selengkapnya tentang pengujian dengan token JWT, lihat Membuat token dengan dotnet user-jwts.
Buat file dokumentasi XML pada waktu kompilasi.
Lihat GenerateDocumentationFile untuk informasi selengkapnya.
Langkah berikutnya
Oleh Christoph Nienaber dan Rico Suter
Swagger (OpenAPI) adalah spesifikasi agnostik bahasa untuk menjelaskan REST API. Ini memungkinkan komputer dan manusia untuk memahami kemampuan REST API tanpa akses langsung ke kode sumber. Tujuan utamanya adalah untuk:
- Minimalkan jumlah pekerjaan yang diperlukan untuk menyambungkan layanan yang dipisahkan.
- Kurangi jumlah waktu yang diperlukan untuk mendokumentasikan layanan secara akurat.
Dua implementasi OpenAPI utama untuk .NET adalah Swashbuckle dan NSwag, lihat:
OpenAPI vs. Swagger
Proyek Swagger di sumbangkan ke OpenAPI Initiative pada tahun 2015 dan sejak itu disebut sebagai OpenAPI. Kedua nama digunakan secara bergantian. Namun, "OpenAPI" mengacu pada spesifikasinya. "Swagger" mengacu pada keluarga produk sumber terbuka dan komersial dari SmartBear yang bekerja dengan Spesifikasi OpenAPI. Produk sumber terbuka berikutnya, seperti OpenAPIGenerator, juga termasuk dalam nama keluarga Swagger, meskipun tidak dirilis oleh SmartBear.
Singkatnya:
- OpenAPI adalah spesifikasi.
- Swagger adalah alat yang menggunakan spesifikasi OpenAPI. Misalnya, OpenAPIGenerator dan SwaggerUI.
Spesifikasi OpenAPI (openapi.json
)
Spesifikasi OpenAPI adalah dokumen yang menjelaskan kemampuan API Anda. Dokumen didasarkan pada XML dan anotasi atribut dalam pengontrol dan model. Ini adalah bagian inti dari alur OpenAPI dan digunakan untuk mendorong alat seperti SwaggerUI. Secara default, ini bernama openapi.json
. Berikut adalah contoh spesifikasi OpenAPI, dikurangi untuk brevity:
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Antarmuka Pengguna Swagger
UI Swagger menawarkan UI berbasis web yang menyediakan informasi tentang layanan, menggunakan spesifikasi OpenAPI yang dihasilkan. Baik Swashbuckle maupun NSwag menyertakan versi UI Swagger yang disematkan, sehingga dapat dihosting di aplikasi ASP.NET Core Anda menggunakan panggilan pendaftaran middleware. Antarmuka pengguna web terlihat seperti ini:
Setiap metode tindakan publik di pengontrol Anda dapat diuji dari UI. Pilih nama metode untuk memperluas bagian. Tambahkan parameter yang diperlukan, dan pilih Cobalah!.
Catatan
Versi UI Swagger yang digunakan untuk cuplikan layar adalah versi 2. Untuk contoh versi 3, lihat Contoh petstore.
Langkah berikutnya
ASP.NET Core
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk