เอกสาร API โดยใช้ Swashbuckle

เสร็จสมบูรณ์เมื่อ

Swashbuckle คือแพคเกจ NuGet ที่มีวิธีการสร้างเอกสาร Swagger โดยอัตโนมัติสําหรับโครงการ API เว็บ ASP.NET Swagger เป็นเครื่องมือที่ช่วยให้นักพัฒนาออกแบบ สร้าง เอกสาร และใช้ RESTful API ด้วย Swashbuckle คุณสามารถเพิ่มเอกสาร Swagger ไปยังโครงการ API เว็บของคุณได้อย่างง่ายดายโดยใส่คําอธิบายประกอบโค้ดของคุณด้วยแอตทริบิวต์ที่อธิบายจุดสิ้นสุด API พารามิเตอร์ และคําตอบของคุณ Swashbuckle ใช้ข้อมูลนี้เพื่อสร้างไฟล์ Swagger JSON ซึ่งสามารถใช้เพื่อสร้างเอกสาร API แบบโต้ตอบ SDK ไคลเอ็นต์ และอื่น ๆ ได้

มีสามองค์ประกอบหลักในการ Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: แบบจําลองวัตถุ Swagger และมิดเดิลแวร์เพื่อเปิดวัตถุ SwaggerDocument เป็นจุดสิ้นสุด JSON

• Swashbuckle.AspNetCore.SwaggerGen: ตัวสร้าง Swagger ที่สร้างวัตถุ SwaggerDocument โดยตรงจากเส้นทาง ตัวควบคุม และแบบจําลองของคุณ โดยทั่วไปแล้วจะรวมกับมิดเดิลแวร์จุดสิ้นสุด Swagger เพื่อแสดง Swagger JSON โดยอัตโนมัติ

• Swashbuckle.AspNetCore.SwaggerUI: เครื่องมือ UI เวอร์ชันฝังตัวของ Swagger ซึ่งตีความ Swagger JSON เพื่อสร้างประสบการณ์ที่สมบูรณ์และปรับแต่งได้สําหรับการอธิบายฟังก์ชันการทํางานของ API เว็บ ซึ่งรวมถึงสายรัดข้อสอบที่มีอยู่ภายในสําหรับวิธีการสาธารณะ

คําสั่ง dotnet add ต่อไปนี้ติดตั้งแพคเกจ Swashbuckle NuGet:

dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0

เพิ่มและกําหนดค่า Middleware ของ Swagger

เพิ่มตัวสร้าง Swagger ไปยังคอลเลกชันบริการใน Program.cs

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

โน้ต

การเรียกไปยัง AddEndpointsApiExplorer ที่แสดงในตัวอย่างก่อนหน้านี้จําเป็นสําหรับ API ที่น้อยที่สุดเท่านั้น

เปิดใช้งานมิดเดิลแวร์สําหรับการให้บริการเอกสาร JSON ที่สร้างขึ้นและ Swagger UI ยังอยู่ใน Program.cs:

app.UseSwagger();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI();
}

จุดสิ้นสุดเริ่มต้นสําหรับ Swagger UI คือ http:<hostname>:<port>/swagger

โน้ต

SwaggerUI มีประโยชน์มากในสภาพแวดล้อมการพัฒนาของคุณ สามารถเปิดใช้งานในการผลิต แต่คุณควรพิจารณาความต้องการด้านความปลอดภัยใด ๆ สําหรับแอปพลิเคชันเฉพาะของคุณก่อนที่จะทําเช่นนั้น

ปรับแต่งและขยายเอกสารประกอบ Swagger

Swagger มีตัวเลือกสําหรับการทําเอกสารรูปแบบวัตถุ และการกําหนด UI เอง การดําเนินการกําหนดค่าที่ส่งผ่านไปยังวิธี AddSwaggerGen สามารถรวมข้อมูลเพิ่มเติมผ่านคลาส OpenApiInfo ได้

ตัวอย่างรหัสต่อไปนี้แสดงวิธีการเพิ่มข้อมูลเพื่อแสดงในเอกสาร API

// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Fruit API",
        Description = "API for managing a list of fruit their stock status.",
        TermsOfService = new Uri("https://example.com/terms")
    });
});

Swagger UI แสดงเวอร์ชันและข้อมูลที่เพิ่ม:

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

app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
    db.Fruits.Add(fruit);
    await db.SaveChangesAsync();

    return Results.Created($"/{fruit.Id}", fruit);
})
    .Produces<Fruit>(201)
    .WithTags("post", "fruits")
    .WithSummary("Create a new fruit");

Swagger UI แสดงคําอธิบายการจัดกลุ่มและสรุปที่ระบุ