Akademi C# · Pelajaran

Menjana Dokumen OpenAPI

Hasilkan spesifikasi API yang boleh dibaca mesin.

Pelajaran 3 daripada 413 langkah

Menjana Dokumen OpenAPI ialah pelajaran Akademi C# percuma di CoddyKit. Ini ialah pelajaran 3 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Akademi C#, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Akademi C# merangkumi sejumlah 4 pelajaran.

Apakah OpenAPI?

OpenAPI ialah penerangan standard yang boleh dibaca mesin bagi API HTTP. Daripadanya, anda boleh menjana dokumentasi, SDK klien dan alat pengujian.

.NET 9 disertakan dengan penjanaan dokumen OpenAPI terbina dalam, yang menggantikan kebergantungan Swashbuckle yang lebih lama untuk banyak aplikasi.

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

Pakej Microsoft.AspNetCore.OpenApi

Sokongan terbina dalam ini terdapat dalam Microsoft.AspNetCore.OpenApi. Dalam templat .NET 9, pakej ini sudah dirujuk.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Daftarkan penjana dokumen dengan AddOpenApi dalam konfigurasi perkhidmatan anda.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi mendedahkan dokumen yang dijana pada satu titik akhir. Secara lalai, dokumen ini disediakan di /openapi/v1.json.

var app = builder.Build();

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

app.Run();

Mengehadkan kepada Pembangunan

Amalan biasa ialah mendedahkan dokumen itu hanya dalam persekitaran pembangunan bagi mengelakkan permukaan API anda terdedah dalam pengeluaran.

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

Menerangkan Titik Akhir

Metadata OpenAPI diperkaya daripada kod anda. Gunakan WithSummary, WithDescription dan WithTags pada titik akhir API minimum.

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

Isytiharkan jenis respons dan kod status supaya dokumen menyenaraikannya dengan tepat.

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

Pengubah Dokumen

Sesuaikan keseluruhan dokumen—tajuk, versi dan pelayan—dengan pengubah dokumen yang dihantar kepada 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 melaraskan operasi individu—contohnya, dengan menambahkan parameter pengepala umum pada setiap titik akhir.

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

Menambahkan Antara Muka Pengguna

Penjana terbina dalam menghasilkan dokumen JSON tetapi tiada antara muka pengguna. Padankannya dengan pemapar seperti Scalar atau Swagger UI.

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

Menjana pada Masa Binaan

Anda boleh menghasilkan fail OpenAPI semasa binaan tanpa menjalankan pelayan menggunakan alat Microsoft.Extensions.ApiDescription.Server, yang berguna untuk penjanaan klien dalam CI.

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

Semakan Pantas

Sahkan asas OpenAPI .NET 9.

Jawab dalam pelajaran interaktif

Imbas Kembali

Anda telah menjana dokumen OpenAPI:

AddOpenApi() mendaftarkan penjana; MapOpenApi() menyediakan JSON.
Perkayakan titik akhir dengan WithSummary, Produces dan penanda.
Pengubah dokumen dan operasi menyesuaikan keluaran.
Padankan dengan Scalar atau Swagger UI untuk paparan interaktif.

Seterusnya: mendokumentasikan API berversi.

Percuma untuk bermula

Pelajari C# dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 93
Pelajaran: 346

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Menjana Dokumen OpenAPI” percuma?

Ya — teks penuh “Menjana Dokumen OpenAPI” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus Akademi C#, tingkat taraf kepada CoddyKit PRO. Kursus Akademi C# merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Menjana Dokumen OpenAPI”?

Hasilkan spesifikasi API yang boleh dibaca mesin. Anda berlatih Akademi C# menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Akademi C#?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Akademi C# di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 3 daripada 4.

Berapa lamakah pelajaran “Menjana Dokumen OpenAPI” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Akademi C# ini?

Ya. Setiap pelajaran Akademi C# menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

← Kembali ke Akademi C#