การจัดทำเอกสาร API ที่มีหลายเวอร์ชัน

หนึ่งเอกสารต่อหนึ่งเวอร์ชัน

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

ตัวให้บริการคำอธิบายเวอร์ชันของ API

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

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

การลงทะเบียนเอกสารต่อหนึ่งเวอร์ชัน

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

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

การกรองจุดปลายทางไปยังเอกสารที่ถูกต้อง

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

การแมปเอกสาร

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

การกำหนดข้อมูลเฉพาะเอกสาร

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

การทำเครื่องหมายเวอร์ชันที่เลิกใช้แล้วในเอกสาร

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

การแทนที่เวอร์ชันใน URL

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

แท็บส่วนติดต่อผู้ใช้ต่อหนึ่งเวอร์ชัน

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

การจัดทำเอกสารโครงสร้างคำขอและการตอบกลับ

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

ประกอบทุกส่วนเข้าด้วยกัน

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

ตรวจสอบความเข้าใจ

สรุปทบทวน