Service Fabric: สร้าง Stateless Web Api ด้วย Asp.Net.Core และสร้าง Api Doc ด้วย Swagger.io

ไทย/Eng
Service Fabric คือไมโครเซอร์วิสที่มีความเสถียรภาพ และรองรับการขยายของการใช้งานเซิฟเวอร์ Service Fabric ประกอบไปด้วย 2 เซอร์วิสหลักๆ ได้แก่ Stateless (ไม่เก็บ state) และ Stateful (เก็บ state) โดยในบทความนี้ จะพัฒนา Web API ที่ไม่ได้มีการเก็บ state ใดๆ ดังนั้นจึงเลือกใช้ Stateless (Stateful ก็ไม่แตกต่างกัน)

Swagger.io เป็น framework ที่ช่วยนักพัฒนาในการออกแบบ และสร้างเอกสารสำหรับ RESTful Web Services. สำหรับ Asp.Net Core มีไลบรารีหลายตัวที่ใช้ Swagger.io โดยไลบรารีที่ผมถนัดและใช้บ่อยที่สุดคือ Swashbuckle เนื่องจากใช้งานง่าย และสามารถสร้าง API document จาก Controller แบบอัตโนมัติ

สิ่งที่ต้องเตรียม

  1. Visual Studio – ในบทความนี้ใช้ VS2017 Preview 2 โดยใช้ .NET เวอร์ชัน 4.6.1
  2. Service Fabric SDK – ดูวิธีติดตั้ง

โค้ดฉบับเต็มของโปรเจ็ค สามารถดูได้ที่นี่

เริ่มกันเลย

    1. เปิด Visual Studio และสร้างโปรเจ็คใหม่

    1. ในหน้าเลือก service เลือก “Stateless ASP.NET Core”

    1. ก่อนอื่น, คุณต้องติดตั้งแพคเกจ NuGet 2 แพคเกจได้แก่ “Swashbuckle.AspNetCore” และ “Microsoft.AspNetCore.StaticFiles”

    1. เปิดไฟล์ที่ชื่อว่า “Startup.cs”
    2. ในเมธอด “Configure” เพิ่มโค้ดต่อไปนี้
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
    1. นำโปรเจคขึ้นคลัสเตอร์ (ในบทความนี้ใช้ localhost) จากนั้นไปที่ cluster explorer (สำหรับ local cluster, ไปที่ “https://localhost:19080/Explorer/”) สุดท้าย ไปที่แอปของเรา เพื่อไปเอา url สำหรับ Web API ของเรา

    1. ไปที่ “http://localhost:8994/swagger/” คุณจะเห็น api document ที่ถูกสร้างโดย Swagger.io

    1. Swashbuckle จะทำการสร้าง APIs จากทุกๆ controllers ในโปรเจ็ค แต่ถ้าคุณต้องการจะซ่อนบางเมธอดหรือบางคลาส คุณสามารถทำได้โดยเพิ่ม attribute ต่อไปนี้
[ApiExplorerSettings(IgnoreApi = true)]
    1. สมมุติว่าผมต้องการซ่อน ValuesController จากเอกสาร ผมก็ใส่ attribute จากข้อก่อนหน้านี้ไปที่ ValuesController แล้วผลลัพธ์ที่ได้จะเป็นดังนี้

 

ถึงตอนนี้ ทุกครั้งที่เราเพิ่ม แก้ไข หรือลบ API เอกสารก็จะถูกสร้างและอัพเดทโดยอัตโนมัติ ง่ายใช่ไหมหล่ะ? แต่ตอนนี้เรายังไม่สามารถเพิ่มคำอธิบายใดๆ ในเอกสารของเราได้เลย ดังนั้นเราจึงต้องมีการติดตั้งเพิ่ม โดยวิธีที่ผมเลือกใช้คือ XMLDocument ที่เป็น build-in ของ .NET framework

    1. ไปที่ property ของโปรเจ็ค แล้วไปที่ “Build” ติ๊กถูกที่ “XML documentation file” จากนั้น path ของไฟล์ xml จะปรากฏขึ้นมา ให้คัดลอก (copy) เก็บไว้ อย่างเช่นในโปรเจ็คนี้ จะมีชื่อว่า “PersonApi.xml”

    1. เปิดไฟล์ “Startup.cs” อีกครั้ง และปรับแก้เมธอด ConfigureServices ใหม่ และควรมีลักษณะประมาณนี้
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

        var basePath = AppContext.BaseDirectory;
        var xmlPath = Path.Combine(basePath, "PersonApi.xml");
        c.IncludeXmlComments(xmlPath);
    });
}
    1. XMLDocument สามารถเพิ่มได้โดยใช้ “///” ตามด้วย XML syntax ที่บ่งบอกถึงรายละเอียดของ API ยกตัวอย่างสำหรับเมธอด “Get” ของ ValuesController ดังนี้
// GET api/values
/// 

/// Retrieves all values
///

/// Awesomeness! /// There are the values /// No values found /// Cannot retrieve values for a moment. [HttpGet] [ProducesResponseType(typeof(List), 200)] [ProducesResponseType(typeof(IDictionary), 400)] [ProducesResponseType(typeof(void), 500)] public IEnumerable Get() { return new string[] { “value1”, “value2” }; }

    1. ผลลัพธ์ที่ได้ จะมีลักษณะประมาณนี้

  1. สำหรับการใช้งานเพิ่มเติมของ .NET XMLDocument และ Swagger document เดี๋ยวผมจะมาพูดต่อในบทความถัดไป

แล้วเจอกันใหม่.
Happy Coding.

Leave a Reply

Your email address will not be published. Required fields are marked *