การจัดการ API ของคุณหลายเวอร์ชันด้วย .NET และ Swagger

การกำหนดเวอร์ชัน REST API เป็นส่วนสำคัญในการรักษา API ที่ประสบความสำเร็จและได้รับการออกแบบมาอย่างดี ด้วยการใส่หมายเลขเวอร์ชันใน URL หรือส่วนหัวของคำขอ HTTP นักพัฒนาสามารถมั่นใจได้ว่าไคลเอนต์ของ API ใช้เวอร์ชันที่ถูกต้องและสามารถทำการเปลี่ยนแปลงกับ API ได้โดยไม่ทำให้ไคลเอนต์ที่มีอยู่เสียหาย มีหลายวิธีในการกำหนดเวอร์ชัน REST API รวมถึงการใช้หมายเลขเวอร์ชันใน URL การใช้ส่วนหัว Accept และการใช้ส่วนหัวแบบกำหนดเอง ในบทความนี้ เราจะสำรวจแนวทางต่างๆ ในการกำหนดเวอร์ชัน REST API และหารือเกี่ยวกับข้อดีข้อเสียของแต่ละแนวทาง นอกจากนี้เรายังจะดูแนวทางปฏิบัติที่ดีที่สุดบางประการสำหรับการนำการกำหนดเวอร์ชัน REST API ไปใช้ในโปรเจ็กต์ของคุณเองด้วย

เมื่อพูดถึงการสร้าง REST API ใน .NET การกำหนดเวอร์ชันถือเป็นข้อพิจารณาที่สำคัญ ด้วยการใส่หมายเลขเวอร์ชันใน URL หรือส่วนหัวของคำขอ HTTP นักพัฒนาสามารถมั่นใจได้ว่าไคลเอนต์ของ API ใช้เวอร์ชันที่ถูกต้องและสามารถทำการเปลี่ยนแปลงกับ API ได้โดยไม่ทำให้ไคลเอนต์ที่มีอยู่เสียหาย มีหลายวิธีในการกำหนดเวอร์ชัน REST API ใน .NET รวมถึงการใช้หมายเลขเวอร์ชันใน URL การใช้ส่วนหัว Accept และการใช้ส่วนหัวแบบกำหนดเอง ในบทความนี้ เราจะสำรวจแนวทางต่างๆ ในการกำหนดเวอร์ชัน REST API ใน .NET และหารือเกี่ยวกับข้อดีข้อเสียของแต่ละแนวทาง นอกจากนี้เรายังจะดูแนวทางปฏิบัติที่ดีที่สุดบางประการสำหรับการนำการกำหนดเวอร์ชัน REST API ไปใช้ในโครงการ .NET ของคุณ

วิธีทั่วไปวิธีหนึ่งในการกำหนดเวอร์ชัน REST API ใน .NET คือการใช้หมายเลขเวอร์ชันใน URL ตัวอย่างเช่น URL สำหรับ API เวอร์ชัน 1 อาจมีลักษณะดังนี้:

https://www.example.com/api/v1/

การใช้หมายเลขเวอร์ชันใน URL มีข้อดีคือง่ายต่อการเข้าใจและนำไปใช้ นอกจากนี้ยังทำให้ไคลเอนต์ทราบอย่างชัดเจนว่าพวกเขากำลังใช้เวอร์ชันใดอยู่ อย่างไรก็ตาม การใช้หมายเลขเวอร์ชันใน URL อาจทำให้การสนับสนุน API หลายเวอร์ชันพร้อมกันได้ยาก นอกจากนี้ยังอาจทำให้การเปลี่ยนแปลง API เป็นเรื่องยาก เนื่องจากการเปลี่ยนแปลงใดๆ ที่ทำให้ไคลเอ็นต์ที่มีอยู่เสียหายจะต้องเปลี่ยน URL ของ API

อีกวิธีหนึ่งในการกำหนดเวอร์ชัน REST API ใน .NET คือการใช้ส่วนหัว Accept ซึ่งช่วยให้ไคลเอ็นต์ของ API สามารถระบุเวอร์ชันของ API ที่พวกเขาต้องการใช้ ตัวอย่างเช่น ลูกค้าอาจส่งคำขอในลักษณะนี้:

GET /api/products HTTP/1.1
Host: www.example.com
Accept: application/vnd.example-v1+json
ample-v1+json

การใช้ส่วนหัว Accept มีข้อดีคือทำให้รองรับ API หลายเวอร์ชันพร้อมกันได้ง่ายขึ้น นอกจากนี้ยังอนุญาตให้ผู้ให้บริการ API ทำการเปลี่ยนแปลง API โดยไม่ต้องเปลี่ยน URL อย่างไรก็ตาม การใช้ส่วนหัว Accept อาจซับซ้อนกว่าในการติดตั้ง และอาจไม่ใช้งานง่ายสำหรับลูกค้าของ API

แนวทางที่สามในการกำหนดเวอร์ชัน REST API ใน .NET คือส่วนหัวที่กำหนดเอง ซึ่งช่วยให้ผู้ให้บริการ API สามารถระบุเวอร์ชันของ API ในส่วนหัว HTTP ที่กำหนดเอง แทนที่จะระบุใน URL หรือส่วนหัว Accept ตัวอย่างเช่น ผู้ให้บริการ API อาจระบุเวอร์ชันของ API ดังนี้:

GET /api/products HTTP/1.1
Host: www.example.com
X-API-Version: 1
HTTP/1.1 Host: www.example.com X-API-Version: 1

การใช้ส่วนหัวแบบกำหนดเองมีข้อดีคือมีความยืดหยุ่น และช่วยให้ผู้ให้บริการ API เลือกรูปแบบการกำหนดเวอร์ชันที่ดีที่สุดสำหรับ API ของตนได้ อย่างไรก็ตาม การดำเนินการยังอาจซับซ้อนกว่าและอาจไม่ใช้งานง่ายสำหรับลูกค้าของ API

ตั้งค่าการกำหนดเวอร์ชัน API ใน .Net 6

หากต้องการตั้งค่าการกำหนดเวอร์ชัน API ใน .NET คุณต้องติดตั้งแพ็คเกจ NuGet สองแพ็คเกจ:

Microsoft.AspNetCore.Mvc.Versioning
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

แพ็คเกจเหล่านี้ให้การสนับสนุนสำหรับการนำการกำหนดเวอร์ชัน API ไปใช้และสร้างข้อมูลเมตาเกี่ยวกับ API ตามลำดับ คุณสามารถติดตั้งทั้งสองแพ็คเกจได้โดยใช้คำสั่งต่อไปนี้:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

หลังจากติดตั้งแพ็คเกจ คุณสามารถใช้แพ็คเกจเหล่านี้เพื่อเพิ่มข้อมูลเวอร์ชันให้กับตำแหน่งข้อมูล URL ของ API ของคุณหรือในส่วนหัวของคำขอ วิธีนี้สามารถช่วยให้คุณรักษาความเข้ากันได้แบบย้อนหลังและจัดการ API หลายเวอร์ชันของคุณได้ ข้อมูลเมตาที่สร้างโดยแพ็คเกจ ApiExplorer อาจมีประโยชน์สำหรับการสร้างเอกสารเชิงโต้ตอบหรือสำหรับการทดสอบจุดสิ้นสุด API

คุณต้องเพิ่มโค้ดต่อไปนี้ใน Program.cs หลังจากติดตั้งแพ็คเกจ

builder.Services.AddApiVersioning(opt =>
{
    opt.DefaultApiVersion = new ApiVersion(1, 0);
    opt.AssumeDefaultVersionWhenUnspecified = true;
    opt.ReportApiVersions = true;
    opt.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(),
                                                    new HeaderApiVersionReader("x-api-version"),
                                                    new MediaTypeApiVersionReader("x-api-version"));
});

builder.Services.AddVersionedApiExplorer(setup =>
{
    setup.GroupNameFormat = "'v'VVV";
    setup.SubstituteApiVersionInUrl = true;
});

ตอนนี้เรามีการตั้งค่าการกำหนดเวอร์ชัน API และพร้อมแล้ว เรามาลองใช้มันเพื่อกำหนดเวอร์ชันของคอนโทรลเลอร์กันดีกว่า

สร้างโฟลเดอร์เวอร์ชัน 2 โฟลเดอร์และโฟลเดอร์ Controller และสร้างตัวควบคุมผู้ใช้ 2 ตัว

หากต้องการใช้การกำหนดเวอร์ชัน API ใน .NET คุณสามารถใช้แอตทริบิวต์ เช่น Route เพื่อระบุตำแหน่งข้อมูล URL หรือส่วนหัวสำหรับการเข้าถึง API เวอร์ชันต่างๆ ของคุณได้ ตัวอย่างเช่น คุณสามารถใช้แอตทริบิวต์ Route กับพารามิเตอร์ apiVersion เพื่อระบุหมายเลขเวอร์ชันในจุดสิ้นสุด URL ได้ดังนี้:

[Route("api/v{version:apiVersion}/[controller]")]This will allow you to access different versions of your API using the version number in the URL.

หรือคุณสามารถใช้แอตทริบิวต์ Route โดยไม่มีพารามิเตอร์ apiVersion เพื่อระบุจุดสิ้นสุดเริ่มต้น และใช้ส่วนหัว x-api-version เพื่อระบุเวอร์ชันของ API ในคำขอ ตัวอย่างเช่น:

[Route("api/[controller]")]

ด้วยแนวทางนี้ ลูกค้าสามารถระบุเวอร์ชันของ API ที่ต้องการใช้โดยใช้ส่วนหัว x-api-version ในคำขอของตนได้ สิ่งนี้มีประโยชน์หากคุณต้องการอนุญาตให้ไคลเอ็นต์เข้าถึงเวอร์ชันต่างๆ ของ API ของคุณโดยใช้ตำแหน่งข้อมูลเดียวกัน

ภายใต้ v1 Folder สร้างตัวควบคุมผู้ใช้

using Microsoft.AspNetCore.Mvc;

namespace WebApiVersioningTest.Controllers.V1;


[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Route("api/[controller]")]
[ApiVersion("1.0")]
public class UserController : ControllerBase
{


    [MapToApiVersion("1.0")]
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("V1");
    }
}

ภายใต้ v2 Folder สร้างตัวควบคุม User V2:

using Microsoft.AspNetCore.Mvc;

namespace WebApiVersioningTest.Controllers.V2;


[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Route("api/[controller]")]
[ApiVersion("2.0")]
public class UserController : ControllerBase
{


    [MapToApiVersion("2.0")]
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("V2");
    }
}

การกำหนดค่าการกำหนดเวอร์ชัน Swagger

หากต้องการกำหนดค่า Swagger ให้ทำงานกับ API เวอร์ชันต่างๆ ใน .NET คุณสามารถใช้อินเทอร์เฟซ IConfigureNamedOptions<SwaggerGenOptions> และใช้เพื่อลงทะเบียน API แต่ละเวอร์ชันและระบุเวอร์ชันเริ่มต้นได้ ซึ่งสามารถทำได้โดยการสร้างคลาส ConfigureSwaggerOptions ที่ใช้เมธอด Configure และอินเทอร์เฟซ IConfigureNamedOptions<SwaggerGenOptions> เช่นนี้:

public class ConfigureSwaggerOptions
    : IConfigureNamedOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _provider;

    public ConfigureSwaggerOptions(
        IApiVersionDescriptionProvider provider)
    {
        _provider = provider;
    }

    /// <summary>
    /// Configure each API discovered for Swagger Documentation
    /// </summary>
    /// <param name="options"></param>
    public void Configure(SwaggerGenOptions options)
    {
        // add swagger document for every API version discovered
        foreach (var description in _provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                CreateVersionInfo(description));
        }
    }

    /// <summary>
    /// Configure Swagger Options. Inherited from the Interface
    /// </summary>
    /// <param name="name"></param>
    /// <param name="options"></param>
    public void Configure(string name, SwaggerGenOptions options)
    {
        Configure(options);
    }

    /// <summary>
    /// Create information about the version of the API
    /// </summary>
    /// <param name="description"></param>
    /// <returns>Information about the API</returns>
    private OpenApiInfo CreateVersionInfo(
            ApiVersionDescription desc)
    {
        var info = new OpenApiInfo()
        {
            Title = ".NET Core (.NET 6) Web API",
            Version = desc.ApiVersion.ToString()
        };

        if (desc.IsDeprecated)
        {
            info.Description += " This API version has been deprecated. Please use one of the new APIs available from the explorer.";
        }

        return info;
    }
}

หลังจากสร้างคลาสนี้แล้ว คุณสามารถเพิ่มโค้ดต่อไปนี้ลงในไฟล์ Program.cs ของคุณเพื่อใช้ในการกำหนดค่า Swagger:

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    var apiVersionDescriptionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json",
                description.GroupName.ToUpperInvariant());
        }
    });
}

หลังจากติดตั้งโค้ดนี้แล้ว Swagger UI ควรแสดงเอกสารประกอบสำหรับ API แต่ละเวอร์ชัน สิ่งนี้มีประโยชน์ในการให้ข้อมูลแก่ผู้ใช้ API เกี่ยวกับเวอร์ชันต่างๆ ของ API และสำหรับการทดสอบ API เวอร์ชันต่างๆ

โดยสรุป มีหลายวิธีในการกำหนดเวอร์ชัน REST API ใน .NET ซึ่งแต่ละวิธีก็มีข้อดีและข้อเสียต่างกันไป แนวทางที่ดีที่สุดสำหรับสถานการณ์ของคุณจะขึ้นอยู่กับข้อกำหนดเฉพาะของ API และความชอบของทีมของคุณ สิ่งสำคัญคือต้องพิจารณาตัวเลือกทั้งหมดอย่างรอบคอบ และเลือกแนวทางที่เหมาะกับสถานการณ์ของคุณมากที่สุด

รหัสเต็มสำหรับโครงการนี้สามารถพบได้ในพื้นที่เก็บข้อมูลต่อไปนี้: https://github.com/saideldah/api-versioining-dot-net-6

การจัดการ API ของคุณหลายเวอร์ชันด้วย .NET และ Swagger

ตั้งค่าการกำหนดเวอร์ชัน API ใน .Net 6

การกำหนดค่าการกำหนดเวอร์ชัน Swagger

คำถามในหัวข้อ