ASP.NET Core API Reference with Scalar

Intro

หลายๆ คนอาจจะพอทราบ หรือรับรู้ข่าวมาบ้างแล้ว ว่าใน .NET 9 นั้นทาง Microsoft จะถอด Swagger ออกจาก API template ของ ASP.NET Core Application Project นั่นเอง ส่วนเหตุผลที่ Microsoft ถอดออก น่าจะเกิดจาก maintainer ของ repository นั้นอาจจะไม่ได้ active เท่าที่ควร Ref: https://github.com/dotnet/aspnetcore/issues/54599 หรือทาง Microsoft เองอาจจะมองเห็น tools ตัวอื่นที่อาจจะดีกว่าก็เป็นได้ และ tool ตัวนั้นก็คงจะเป็นใครไปไม่ได้ถ้าไม่ใช้ Scalar

Scalar

Scalar นั้นเป็นเครื่องมือสำหรับทำเอกสาร สารบัญ และ ทดสอบ APIs ของ Application ที่เราสร้างขึ้นมาโดยอิงตามมาตราฐานของ OpenAPI โดย Scalar นั้นค่อนข้างจะมี UX ที่ใกล้เคียงกับ Client tools หลายๆ ตัวเช่น Postman หรือ Thunder Client ซึ่งจะต่างกับทาง Swagger พอสมควร และในเรื่อง Document หรืองานเอกสาร ก็สามารถทำได้ดีกว่า Swagger เช่นกัน

Usage

สำหรับใครที่ไม่อยากรอ .NET 9 อยากจะใช้ ตัว Scalar บน .NET 8 เลยก็สามารถทำได้ง่ายๆด้วยการใช้งานร่วมกับ Swagger ไปก่อน จากนั้นหลังจาก .NET 9 Release ก็สามารถถอด Swagger ออก และไปใช้ OpenApi Library จากทาง Microsoft แทน

Require Dependency

dotnet add package Scalar.AspNetCore

Integrating Scalar with Swagger For .NET8

เนื่องจากใน .NET 8 นั้น Library หลักจาก Microsoft (Microsoft.AspNetCore.OpenApi) ยังไม่รองรับการสร้าง OpenApi Document เราเลยยังคงต้องพึ่งพา Swagger ในการสร้าง OpenApi Document ก่อน แต่เราจะทำการ ถอดตัว Swagger UI ออกไป และนำ Scalar มาใส่แทน

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Title = "My API",
        Version = "v1"
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // Add swagger middleware for generate OpenApi document.
    app.UseSwagger(c =>
    {
        // change the OpenApi document route template for support Scalar
        // And this will consistent with .NET9 default OpenApi route in future
        c.RouteTemplate = "openapi/{documentName}.json";
    });

    // Add Scalar Endpoint
    app.MapScalarApiReference();

}

app.Run();

โดยหลักๆ แล้วเราจะทำการแก้ไขแค่ตัว OpenApi document route ให้สอดคล้องกับ OpenApi route ในอนาคต และเรียกใช้ MapScalarApiReference() ใน application pipeline สำหรับ api reference endpoint.

Run and Test

หลังจากถอด Swagger UI และใส่ Scalar เข้าไปแทนแล้ว เราสามารถ ทดสอบด้วยการ Run Project และเปิดผ่าน browser ไปที่ /scalar/v1

For .NET9

ในอนาคตนั้นหลังจาก .NET 9 Release ออกมาแล้วและทาง project ก็พร้อมสำหรับ Upgrade ขึ้นไปเป็น .NET 9 แล้ว ในส่วนของ Api Reference เองนั้นเราสามารถถอดการเรียกใช้ Swagger ออก และทำการ Configure ServiceCollection ด้วย AddOpenApi() และ MapOpenApi() สำหรับ OpenApi document endpoint ในส่วนของ Application Pipeline

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

if (app.Environment.IsDevelopment())
{
    // Add Scalar Endpoint
    app.MapScalarApiReference();

}

app.Run();

เท่านี้ Project ของเราก็ไม่ต้องพึ่งพา Swagger อีกต่อไป

สำหรับคนที่สนใจ อยากจะลองเล่นกับ Scalar ดูสามารถไปลองกับ demo ของทาง Scalar ได้ที่ https://docs.scalar.com/swagger-editor