C# Academy · Pelajaran

Mendokumentasikan API Berversi

Sediakan dokumentasi untuk beberapa versi API.

Mendokumentasikan API Berversi adalah pelajaran C# Academy gratis di CoddyKit. Ini adalah pelajaran 4 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar C# Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus C# Academy mencakup 4 pelajaran total.

Satu Dokumen untuk Setiap Versi

Ketika sebuah API memiliki beberapa versi, biasanya Anda memerlukan dokumen OpenAPI terpisah untuk setiap versi agar konsumen hanya melihat titik akhir yang relevan bagi mereka.

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

Penyedia Deskripsi Versi API

Asp.Versioning menyediakan IApiVersionDescriptionProvider, yang mencantumkan setiap versi API yang ditemukan. Lakukan iterasi terhadapnya untuk mendaftarkan satu dokumen per versi.

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

Mendaftarkan Satu Dokumen per Versi

Panggil AddOpenApi satu kali untuk setiap grup versi, lalu beri nama setiap dokumen berdasarkan grup tersebut.

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

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

Memfilter Titik Akhir ke Dokumen yang Tepat

Gunakan pengubah dokumen atau predikat ShouldInclude agar setiap dokumen hanya berisi titik akhir versinya, yang dicocokkan berdasarkan nama grup.

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

Memetakan Dokumen

MapOpenApi dengan pola bawaan menyediakan setiap dokumen bernama di /openapi/{documentName}.json.

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

Mengatur Informasi per Dokumen

Berikan judul dan versi masing-masing dokumen versi melalui pengubah agar dokumentasi dapat menjelaskan dirinya sendiri.

builder.Services.AddOpenApi("v2", options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API v2";
        doc.Info.Version = "2.0";
        return Task.CompletedTask;
    });
});

Menandai Versi Usang dalam Dokumentasi

Jika suatu versi sudah usang, tampilkan informasi tersebut dalam deskripsi dokumennya agar konsumen melihat peringatannya di antarmuka.

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

Mengganti Versi dalam URL

SubstituteApiVersionInUrl = true mengubah token rute {version:apiVersion} menjadi versi konkret (misalnya, v1) dalam dokumen, sehingga jalur terlihat lebih jelas.

// Without: /api/v{version}/products
// With:    /api/v1/products

Satu Tab Antarmuka per Versi

Sebagian besar penampil dapat menampilkan daftar pilihan semua dokumen. Konfigurasikan antarmuka agar mengarah ke JSON setiap versi.

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

Mendokumentasikan Bentuk Permintaan dan Respons

Karena v2 mungkin mengubah DTO, berikan setiap versi tipe DTO-nya sendiri. OpenAPI kemudian secara otomatis menampilkan skema yang berbeda untuk setiap dokumen.

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

Menggabungkan Semuanya

Alur lengkapnya: konfigurasikan pembuatan versi dan penjelajah API, daftarkan satu dokumen OpenApi per versi dengan penyaring, petakan dokumen tersebut, lalu arahkan antarmuka ke masing-masing dokumen.

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

Pemeriksaan Singkat

Pastikan cara dokumen berversi dibuat.

Rekapitulasi

Anda telah mendokumentasikan API berversi:

Daftarkan satu dokumen OpenAPI bernama untuk setiap versi dengan AddOpenApi("vN").
IApiVersionDescriptionProvider mencantumkan versi; ShouldInclude memfilter titik akhir.
SubstituteApiVersionInUrl menampilkan jalur dengan versi konkret.
Arahkan antarmuka ke setiap dokumen untuk mendapatkan tampilan per versi.

Dengan demikian, kursus pembuatan versi dan OpenAPI telah selesai.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Mendokumentasikan API Berversi” gratis?

Ya — teks lengkap “Mendokumentasikan API Berversi” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus C# Academy, upgrade ke CoddyKit PRO. Kursus C# Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Mendokumentasikan API Berversi”?

Sediakan dokumentasi untuk beberapa versi API. Kamu berlatih C# Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai C# Academy?

Tidak diperlukan pengalaman sebelumnya. C# Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 4 dari 4.

Berapa lama pelajaran “Mendokumentasikan API Berversi” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran C# Academy ini?

Ya. Setiap pelajaran C# Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

← Kembali ke C# Academy