0Pricing
C# Academy · บทเรียน

การสร้างเอกสาร OpenAPI

สร้างข้อกำหนด API ที่เครื่องอ่านได้

การสร้างเอกสาร OpenAPI เป็นบทเรียน C# Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 3 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7 บทเรียนนี้เป็นส่วนหนึ่งของเส้นทางการเรียน C# Academy และความก้าวหน้าของคุณจะซิงค์ข้ามเว็บและแอป CoddyKit คอร์ส C# Academy มีบทเรียนทั้งหมด 4 บทเรียน

OpenAPI คืออะไร

OpenAPI คือคำอธิบายมาตรฐานของ HTTP API ที่เครื่องสามารถอ่านได้ จากคำอธิบายนี้ คุณสามารถสร้างเอกสาร ชุด SDK สำหรับไคลเอ็นต์ และเครื่องมือทดสอบได้

.NET 9 มาพร้อมความสามารถในตัวสำหรับสร้างเอกสาร OpenAPI ซึ่งเข้ามาแทนที่การพึ่งพา Swashbuckle แบบเก่าสำหรับแอปจำนวนมาก

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

แพ็กเกจ Microsoft.AspNetCore.OpenApi

การรองรับที่มีมาให้ในตัวอยู่ใน Microsoft.AspNetCore.OpenApi และมีการอ้างอิงแพ็กเกจนี้ไว้แล้วในแม่แบบ .NET 9

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

ลงทะเบียนตัวสร้างเอกสารด้วย AddOpenApi ในการกำหนดค่าบริการของคุณ

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi เปิดเผยเอกสารที่สร้างขึ้นผ่านจุดปลายทาง โดยค่าเริ่มต้นจะให้บริการที่ /openapi/v1.json

var app = builder.Build();

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

app.Run();

จำกัดให้ใช้เฉพาะการพัฒนา

โดยทั่วไปควรเปิดเผยเอกสารเฉพาะในสภาพแวดล้อมการพัฒนา เพื่อป้องกันไม่ให้รายการ API ที่เปิดเผยรั่วไหลในสภาพแวดล้อมจริง

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

การอธิบายจุดปลายทาง

ข้อมูลเมตาของ OpenAPI ได้รับการเติมเต็มจากโค้ดของคุณ ใช้ WithSummary, WithDescription และ WithTags กับจุดปลายทางของ Minimal API

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

การจัดทำเอกสารการตอบกลับ

ประกาศประเภทการตอบกลับและรหัสสถานะ เพื่อให้เอกสารแสดงข้อมูลเหล่านี้ได้อย่างถูกต้อง

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

ตัวแปลงเอกสาร

ปรับแต่งเอกสารทั้งหมด เช่น ชื่อเรื่อง เวอร์ชัน และเซิร์ฟเวอร์ ด้วย ตัวแปลงเอกสาร ที่ส่งให้กับ AddOpenApi

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

ตัวแปลงการดำเนินการ

ตัวแปลงการดำเนินการใช้ปรับแต่งการดำเนินการแต่ละรายการ เช่น เพิ่มพารามิเตอร์ส่วนหัวที่ใช้ร่วมกันให้กับทุกจุดปลายทาง

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

การเพิ่มส่วนติดต่อผู้ใช้

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

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

การสร้างระหว่างการบิลด์

คุณสามารถสร้างไฟล์ OpenAPI ระหว่างการบิลด์ได้โดยไม่ต้องเปิดเซิร์ฟเวอร์ที่กำลังทำงานอยู่ โดยใช้เครื่องมือสำหรับคำอธิบาย API ของส่วนขยาย Microsoft ซึ่งเหมาะสำหรับการสร้างไคลเอ็นต์ใน CI

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

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

ยืนยันพื้นฐาน OpenAPI ของ .NET 9

สรุปทบทวน

คุณได้สร้างเอกสาร OpenAPI แล้ว:

  • AddOpenApi() ลงทะเบียนตัวสร้าง ส่วน MapOpenApi() ให้บริการ JSON
  • เติมข้อมูลให้จุดปลายทางด้วย WithSummary, Produces และแท็ก
  • ตัวแปลงเอกสารและตัวแปลงการดำเนินการใช้ปรับแต่งผลลัพธ์
  • ใช้ร่วมกับสกาลาร์หรือส่วนติดต่อผู้ใช้สแวกเกอร์เพื่อให้มีมุมมองแบบโต้ตอบ

ถัดไป: การจัดทำเอกสาร API ที่มีการจัดการเวอร์ชัน

คำถามที่พบบ่อย

บทเรียน “การสร้างเอกสาร OpenAPI” ฟรีหรือไม่

ใช่ — ข้อความเต็มของ “การสร้างเอกสาร OpenAPI” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส C# Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส C# Academy มีบทเรียนทั้งหมด 4 บทเรียน

คุณจะเรียนรู้อะไรในบทเรียน “การสร้างเอกสาร OpenAPI”

สร้างข้อกำหนด API ที่เครื่องอ่านได้ คุณปฏิบัติ C# Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 24/7 ตอบคำถามของคุณขณะที่คุณไปผ่านบทเรียน

คุณต้องมีประสบการณ์ก่อนที่จะเริ่มเรียน C# Academy หรือไม่

ไม่จำเป็นต้องมีประสบการณ์มาก่อน C# Academy บน CoddyKit ออกแบบมาสำหรับผู้เริ่มต้นไปจนถึงผู้เรียนขั้นสูง คุณสามารถเริ่มต้นที่นี่หรือเริ่มจากตัวแรกและเรียนด้วยความเร็วของคุณเอง นี่คือบทเรียนที่ 3 จากทั้งหมด 4 บทเรียน

บทเรียน “การสร้างเอกสาร OpenAPI” ใช้เวลานานแค่ไหน

บทเรียน CoddyKit ส่วนใหญ่ใช้เวลาประมาณ 5–10 นาที แต่ละบทเรียนจึงสั้นและเป็นแบบโต้ตอบ คุณสามารถก้าวหน้าอย่างต่อเนื่องและกลับมาเรียนต่อจากตรงที่เพิ่งหยุดบนเว็บและแอปได้เลย

ฉันเขียนและรันโค้ดในบทเรียน C# Academy นี้ได้ไหม

ได้ บทเรียน C# Academy ทุกบทมีตัวแก้ไขโค้ดในตัว คุณจึงเขียนและรันโค้ดจริงได้เลยในเบราว์เซอร์ และได้รับข้อเสนอแนะจาก AI ในทันที — ไม่ต้องติดตั้งในเครื่องของคุณ

บทเรียนทั้งหมดในหลักสูตรนี้

  1. กลยุทธ์การกำหนดเวอร์ชัน API
  2. การกำหนดค่า Asp.Versioning
  3. การสร้างเอกสาร OpenAPI
  4. การจัดทำเอกสาร API ที่มีหลายเวอร์ชัน
← กลับไปที่ C# Academy