C# Academy · Pelajaran

Membuat Dokumen OpenAPI

Hasilkan spesifikasi API yang dapat dibaca mesin.

Membuat Dokumen OpenAPI adalah pelajaran C# Academy gratis di CoddyKit. Ini adalah pelajaran 3 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.

Apa Itu OpenAPI?

OpenAPI adalah deskripsi standar API HTTP yang dapat dibaca mesin. Dari deskripsi ini, Anda dapat membuat dokumentasi, SDK klien, dan perkakas pengujian.

.NET 9 menyediakan pembuatan dokumen OpenAPI bawaan, sehingga banyak aplikasi tidak lagi memerlukan dependensi Swashbuckle yang lebih lama.

// OpenAPI document = JSON describing paths, schemas, params

Paket Microsoft.AspNetCore.OpenApi

Dukungan bawaan tersedia di Microsoft.AspNetCore.OpenApi. Pada templat .NET 9, paket ini sudah direferensikan.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Daftarkan pembuat dokumen dengan AddOpenApi dalam konfigurasi layanan.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi menyediakan dokumen yang dihasilkan pada sebuah titik akhir. Secara bawaan, dokumen tersedia di /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Membatasi ke Lingkungan Pengembangan

Umumnya dokumen hanya disediakan dalam lingkungan pengembangan agar cakupan API Anda tidak terbuka di produksi.

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

Mendeskripsikan Titik Akhir

Metadata OpenAPI diperkaya dari kode Anda. Gunakan WithSummary, WithDescription, dan WithTags pada titik akhir API Minimal.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Mendokumentasikan Respons

Nyatakan tipe respons dan kode status agar dokumen mencantumkannya secara akurat.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Pengubah Dokumen

Sesuaikan seluruh dokumen—judul, versi, dan server—dengan pengubah dokumen yang diteruskan ke AddOpenApi.

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

Pengubah Operasi

Pengubah operasi menyesuaikan operasi individual—misalnya, menambahkan parameter header umum ke setiap titik akhir.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Menambahkan Antarmuka

Pembuat bawaan menghasilkan dokumen JSON, tetapi tidak menyediakan antarmuka. Pasangkan dengan penampil seperti Scalar atau Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Membuat saat Build

Anda dapat menghasilkan berkas OpenAPI selama Build (tanpa peladen yang berjalan) menggunakan perkakas Microsoft.Extensions.ApiDescription.Server, yang berguna untuk pembuatan klien di CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Pemeriksaan Singkat

Pastikan dasar-dasar OpenAPI di .NET 9.

Rekapitulasi

Anda telah membuat dokumen OpenAPI:

AddOpenApi() mendaftarkan pembuat dokumen; MapOpenApi() menyediakan JSON.
Perkaya titik akhir dengan WithSummary, Produces, dan label.
Pengubah dokumen dan pengubah operasi menyesuaikan keluaran.
Pasangkan dengan Scalar atau Swagger UI untuk tampilan interaktif.

Berikutnya: mendokumentasikan API berversi.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Membuat Dokumen OpenAPI” gratis?

Ya — teks lengkap “Membuat Dokumen OpenAPI” 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 “Membuat Dokumen OpenAPI”?

Hasilkan spesifikasi API yang dapat dibaca mesin. 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 3 dari 4.

Berapa lama pelajaran “Membuat Dokumen OpenAPI” 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