Mulai menggunakan Swashbuckle dan ASP.NET Core

Catatan

Pembuatan dokumen OpenAPI build-time dengan Swashbuckle tidak didukung di .NET 8 dan yang lebih baru. Untuk alternatif build-time yang didukung, lihat dokumentasi API web ASP.NET Core dengan Swagger / OpenAPI. Pembuatan dokumen run-time masih didukung di .NET 8.

Ada tiga komponen utama untuk Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: model objek Swagger dan middleware untuk mengekspos SwaggerDocument objek sebagai JStitik akhir ON.

• Swashbuckle.AspNetCore.SwaggerGen: generator Swagger yang membangun SwaggerDocument objek langsung dari rute, pengontrol, dan model Anda. Biasanya dikombinasikan dengan middleware titik akhir Swagger untuk secara otomatis mengekspos Swagger JSON.

• Swashbuckle.AspNetCore.SwaggerUI: versi alat UI Swagger yang disematkan. Ini menafsirkan Swagger JSON untuk membangun pengalaman yang kaya dan dapat disesuaikan untuk menjelaskan fungsionalitas API web. Ini termasuk harness uji bawaan untuk metode publik.

Penginstalan paket

Swashbuckle dapat ditambahkan dengan pendekatan berikut:

Visual Studio

• Dari jendela Package Manager Console :

  • Buka Lihat>Konsol Pengelola Paket Windows Lainnya>

  • Navigasikan ke direktori tempat .csproj file ada

  • Jalankan perintah berikut:

    Install-Package Swashbuckle.AspNetCore -Version 6.5.0
    

• Dari dialog Kelola Paket NuGet:

  • Klik kanan proyek di Penjelajah Solusi> Kelola Paket NuGet
  • Atur Sumber paket ke "nuget.org"
  • Pastikan opsi "Sertakan prarilis" diaktifkan
  • Masukkan "Swashbuckle.AspNetCore" di kotak pencarian
  • Pilih paket "Swashbuckle.AspNetCore" terbaru dari tab Telusuri dan klik Instal

Visual Studio untuk Mac

• Klik kanan folder Paket di Pad>Solusi Tambahkan Paket...
• Atur menu drop-down Tambahkan Sumber jendela Paket ke "nuget.org"
• Pastikan opsi "Tampilkan paket pra-rilis" diaktifkan
• Masukkan "Swashbuckle.AspNetCore" di kotak pencarian
• Pilih paket "Swashbuckle.AspNetCore" terbaru dari panel hasil dan klik Tambahkan Paket

Visual Studio Code

Jalankan perintah berikut dari Terminal Terintegrasi:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.5.0

.NET Core CLI

Jalankan perintah berikut:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.5.0

Menambahkan dan mengonfigurasi middleware Swagger

Tambahkan generator Swagger ke koleksi layanan di Program.cs:

builder.Services.AddControllers();

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

Panggilan untuk AddEndpointsApiExplorer ditampilkan dalam contoh sebelumnya hanya diperlukan untuk API minimal. Untuk informasi selengkapnya, lihat posting StackOverflow ini.

Aktifkan middleware untuk melayani dokumen ON yang dihasilkan JSdan antarmuka pengguna Swagger, juga di Program.cs:

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

Kode sebelumnya menambahkan middleware Swagger hanya jika lingkungan saat ini diatur ke Pengembangan. Panggilan UseSwaggerUI metode memungkinkan versi alat antarmuka pengguna Swagger yang disematkan.

Luncurkan aplikasi dan navigasikan ke https://localhost:<port>/swagger/v1/swagger.json. Dokumen yang dihasilkan yang menjelaskan titik akhir muncul seperti yang ditunjukkan dalam spesifikasi OpenAPI (openapi.json).

UI Swagger dapat ditemukan di https://localhost:<port>/swagger. Jelajahi API melalui antarmuka pengguna Swagger dan masukkan dalam program lain.

Tip

Untuk melayani UI Swagger di root aplikasi (https://localhost:<port>/), atur RoutePrefix properti ke string kosong:

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Jika menggunakan direktori dengan IIS atau proksi terbalik, atur titik akhir Swagger ke jalur relatif menggunakan awalan ./ . Contohnya,./swagger/v1/swagger.json. Menggunakan /swagger/v1/swagger.json menginstruksikan aplikasi untuk mencari JSfile ON di akar URL yang sebenarnya (ditambah awalan rute, jika digunakan). Misalnya, gunakan https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json, bukan https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Catatan

Secara default, Swashbuckle menghasilkan dan mengekspos Swagger JSON dalam spesifikasi versi 3.0—secara resmi disebut Spesifikasi OpenAPI. Untuk mendukung kompatibilitas mundur, Anda dapat memilih untuk mengekspos JSON dalam format 2.0 sebagai gantinya. Format 2.0 ini penting untuk integrasi seperti Microsoft Power Apps dan Microsoft Flow yang saat ini mendukung OpenAPI versi 2.0. Untuk memilih format 2.0, atur SerializeAsV2 properti di Program.cs:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Menyesuaikan dan memperluas

Swagger menyediakan opsi untuk mendokumen model objek dan menyesuaikan UI agar sesuai dengan tema Anda.

Info dan deskripsi API

Tindakan konfigurasi yang diteruskan ke AddSwaggerGen metode menambahkan informasi seperti penulis, lisensi, dan deskripsi.

Di Program.cs, impor namespace berikut untuk menggunakan OpenApiInfo kelas :

using Microsoft.OpenApi.Models;

OpenApiInfo Menggunakan kelas , ubah informasi yang ditampilkan di UI:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

UI Swagger menampilkan informasi versi:

Komentar XML

Komentar XML dapat diaktifkan dengan pendekatan berikut:

Visual Studio

• Klik kanan proyek di Penjelajah Solusi dan pilih Edit <project_name>.csproj.
• Tambahkan GenerateDocumentationFile ke .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio untuk Mac

• Dari Pad Solusi, tekan kontrol dan klik nama proyek. Navigasi ke Alat>Edit File.
• Tambahkan GenerateDocumentationFile ke .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Tambahkan GenerateDocumentationFile ke .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

.NET Core CLI

Tambahkan GenerateDocumentationFile ke .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Mengaktifkan komentar XML menyediakan informasi debug untuk jenis publik dan anggota yang tidak terdokumentasi. Jenis dan anggota yang tidak terdokumentasi ditunjukkan oleh pesan peringatan. Misalnya, pesan berikut menunjukkan pelanggaran kode peringatan 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Untuk menyembunyikan peringatan di seluruh proyek, tentukan daftar kode peringatan yang dibatasi titik koma untuk diabaikan dalam file proyek. Menambahkan kode peringatan untuk $(NoWarn); menerapkan nilai default C# juga.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Untuk menekan peringatan hanya untuk anggota tertentu, sertakan kode dalam petunjuk praprosedur peringatan #pragma. Pendekatan ini berguna untuk kode yang tidak boleh diekspos melalui dokumen API. Dalam contoh berikut, kode peringatan CS1591 diabaikan untuk seluruh TodoContext kelas. Penerapan kode peringatan dipulihkan pada penutupan definisi kelas. Tentukan beberapa kode peringatan dengan daftar yang dibatasi koma.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Konfigurasikan Swagger untuk menggunakan file XML yang dihasilkan dengan instruksi sebelumnya. Untuk sistem operasi Linux atau non-Windows, nama dan jalur file dapat peka huruf besar/kecil. Misalnya, TodoApi.XML file valid di Windows tetapi bukan Ubuntu.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Dalam kode sebelumnya, Reflection digunakan untuk membangun nama file XML yang cocok dengan proyek API web. Properti AppContext.BaseDirectory digunakan untuk membuat jalur ke file XML. Beberapa fitur Swagger (misalnya, skema parameter input atau metode HTTP dan kode respons dari atribut masing-masing) berfungsi tanpa menggunakan file dokumentasi XML. Untuk sebagian besar fitur, yaitu ringkasan metode dan deskripsi parameter dan kode respons, penggunaan file XML adalah wajib.

Menambahkan komentar tiga garis miring ke tindakan akan meningkatkan Antarmuka Pengguna Swagger dengan menambahkan deskripsi ke header bagian. <Tambahkan elemen ringkasan> di atas Delete tindakan:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

UI Swagger menampilkan teks dalam elemen kode <summary> sebelumnya:

UI didorong oleh skema ON yang dihasilkan JS:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

<Tambahkan elemen keterangan> ke Create dokumentasi metode tindakan. Ini melengkapi informasi yang ditentukan dalam <summary> elemen dan menyediakan antarmuka pengguna Swagger yang lebih kuat. Konten <remarks> elemen dapat terdiri dari teks, JSON, atau XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Perhatikan peningkatan UI dengan komentar tambahan ini:

Anotasi data

Tandai model dengan atribut, yang ditemukan di System.ComponentModel.DataAnnotations namespace layanan, untuk membantu mendorong komponen antarmuka pengguna Swagger.

[Required] Tambahkan atribut ke Name properti TodoItem kelas :

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Kehadiran atribut ini mengubah perilaku UI dan mengubah skema ON yang mendasar JS:

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

[Produces("application/json")] Tambahkan atribut ke pengontrol API. Tujuannya adalah untuk menyatakan bahwa tindakan pengontrol mendukung jenis konten respons aplikasi/json:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

Drop-down Jenis media memilih tipe isi ini sebagai default untuk tindakan GET pengontrol:

Ketika penggunaan anotasi data di API web meningkat, halaman bantuan UI dan API menjadi lebih deskriptif dan berguna.

Menjelaskan jenis respons

Pengembang yang menggunakan API web paling peduli dengan apa yang dikembalikan—khususnya jenis respons dan kode kesalahan (jika tidak standar). Jenis respons dan kode kesalahan ditandai dalam komentar XML dan anotasi data.

Tindakan mengembalikan Create kode status HTTP 201 saat berhasil. Kode status HTTP 400 dikembalikan ketika isi permintaan yang diposting null. Tanpa dokumentasi yang tepat di antarmuka pengguna Swagger, konsumen tidak memiliki pengetahuan tentang hasil yang diharapkan ini. Perbaiki masalah tersebut dengan menambahkan baris yang disorot dalam contoh berikut:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

UI Swagger sekarang dengan jelas mendokuensikan kode respons HTTP yang diharapkan:

Konvensi dapat digunakan sebagai alternatif untuk mendekorasi tindakan individu secara eksplisit dengan [ProducesResponseType]. Untuk informasi selengkapnya, lihat Menggunakan konvensi API web.

Untuk mendukung [ProducesResponseType] dekorasi, paket Swashbuckle.AspNetCore.Annotations menawarkan ekstensi untuk mengaktifkan dan memperkaya respons, skema, dan metadata parameter.

Menyesuaikan UI

UI default berfungsi dan dapat disajikan. Namun, halaman dokumentasi API harus mewakili merek atau tema Anda. Mencitrakan komponen Swashbuckle mengharuskan penambahan sumber daya untuk melayani file statis dan membangun struktur folder untuk menghosting file-file tersebut.

Aktifkan Middleware File Statis:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Untuk menyuntikkan lembar gaya CSS tambahan, tambahkan ke folder wwwroot proyek dan tentukan jalur relatif di opsi middleware:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)
• Swagger tidak mengenali komentar atau atribut pada rekaman
• Meningkatkan pengalaman pengembang API dengan dokumentasi Swagger