แต่กระนั้น โปรแกรมเมอร์อย่างเรามักไม่ชอบทำ API Document หรอกครับ เขียนๆไปแค่ให้มี สิ่งที่ได้มักเป็นเอกสารที่ใช้งานได้บ้างไม่ได้บ้าง เพราะเป็นภาษาที่คนเขียนเข้าใจแค่ตัวเอง หรือตัวอย่างไม่ชัดเจน หรือมีข้อมูลใช้งานไม่ครบถ้วน หนักไปกว่านั้นคือ บ่นว่าไม่มีเวลา แล้วก็ไม่ทำมันซะเลย (แต่มีเวลาไปอธิบายให้ผู้ใช้ทีละคนๆ 555)

ดังนั้น จะดีกว่าไหม ถ้าเราเขียนโค้ด API เสร็จ แล้วมีเครื่องมือสร้าง API Document ให้เราได้เลยอัตโนมัติ, อ่ะ ตอบแทนละกัน “ดีว่ะ!”

เครื่องมือหนึ่งที่ผมจะแนะนำในบล็อกนี้ ชื่อว่า Swagger ซึ่งมันสามารถสร้างเอกสารการใช้งาน API (API Document) และเครื่องมือทดสอบให้เราได้ในทันที (Testing Tools) โดยมันจะแปลงจากคำสั่งในโค้ดของเราออกมาให้นั่นเอง

ในบล็อกนี้ผมลองใช้ Swagger กับ .NET Core 2 นะครับ สำหรับภาษาอื่นๆ สามารถหาข้อมูลเพิ่มเติมได้ที่ Swagger Open Source Integrations

ว่าแล้ว เรามาเริ่มทำตามขั้นตอนกันเลย

ติดตั้ง NuGet packages

ให้เราเข้าไปที่โฟลเดอร์ของ API เราก่อน และพิมพ์คำสั่ง add package ดังนี้

[code lang=”shell”]dotnet add api.csproj package Swashbuckle.AspNetCore[/code]

ติดตั้ง Configure Swagger ใน Middleware

เพิ่มโค้ดเข้าไปใน ConfigureServices() ของไฟล์ Startup.cs ดังนี้

[code lang=”csharp”]
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

var basePath = AppContext.BaseDirectory;
var xmlPath = Path.Combine(basePath, "MyApi.xml");
c.IncludeXmlComments(xmlPath);
});
[/code]

จากนั้นให้ใส่ using package ไว้ด้วย (โดยปกติ Editor จะเตือนให้เพิ่มด้วย) ดังนี้

[code lang=”csharp”]using Swashbuckle.AspNetCore.Swagger;[/code]

จะได้ดังภาพนี้

ซึ่ง Title คือชื่อของหน้าเอกสาร ในที่นี้ผมใช้ชื่อ “My API” ส่วนกลุ่มบรรทัดล่างเป็นการขอเปิดใช้งาน Customize ข้อความในรูปแบบของเราเอง ด้วยการระบุข้อมูลเป็น Comment ลงไปในโค้ด (และ Swagger จะทำการเก็บข้อความเหล่านั้นตามไฟล์ XML ที่เราระบุไว้)

จากนั้น เพิ่มโค้ดเข้าไปใน Configure() ของไฟล์ Startup.cs ดังนี้

[code lang=”csharp”]
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
[/code]

จะได้ดังภาพนี้

เป็นอันเสร็จ ให้ทำการ build และ run ใหม่อีกครั้ง เพื่อลองใช้งาน

ทดลองใช้งาน Swagger

ให้เราเปิด browser เข้าไปที่ (แก้ url/port ตามที่คุณตั้งไว้ด้วยนะ)

http://<localhost:port>/swagger/v1/swagger.json

จะเจอข้อความ JSON ที่เป็นชุดคำสั่งของ Swagger

แต่ถ้าต้องการดูสวยงามด้วย Swagger UI ให้เข้าไปที่

http://<localhost:port>/swagger/

จะได้หน้าตาสวยงามแบบนี้ครับ

มันจะแสดงรายการ API ของเราออกมาทั้งหมด ตาม Controller/Method/Route ที่เราได้เขียนไปในโค้ดเลยครับ
และเมื่อเรากดเข้าไปดูในรายละเอียดของแต่ละ API มันก็จะแสดงวิธีการ Access, Data Type, Respond Status, Respond Data, Respond Type ครบถ้วน ดังรูป

หรืออีกตัวอย่างหนึ่ง ผมลองดึงข้อมูลสมาชิกหมายเลข 2 ออกมา ซึ่งในโค้ดผมบอกว่าต้องระบุ Parameter ให้ด้วย ดังนั้น ตัว Swagger มันก็ได้สร้าง Input ให้ผมได้กรอก Parameter นั้นให้อัตโนมัติเลย

คราวนี้ลองมาดูการส่งข้อมูลแบบ HTTP Post บ้าง ซึ่งมันจะไปดึง Data Structure ของ Model ออกมาให้เราเป็นตัวอย่าง (ตามรูปด้านล่าง กล่องสีเหลืองด้านซ้าย) เมื่อกดที่ตัวอย่าง มันจะมากรอกให้ในช่อง Input ซ้ายมือ เราก็ทำการแก้ไขข้อมูลที่ต้องการใช้งาน ซึ่งในที่นี้ผมทดสอบการเพิ่มข้อมูลสมาชิก เมื่อกรอกเสร็จและกดปุ่ม “Tyr it out!” มันก็จะแสดงผลการทำงานออกมาให้เราดังรูปด้านล่าง

การ Customize Document

ถ้าสังเกตดีๆ มี API ตัวหนึ่งที่มีข้อความโผล่มา ว่า “Get Member information from id” ซึ่งอันนี้ผมทำการ Customize เขียนเพิ่มคำอธิบายเข้าไป

ซึ่งในโค้ด API ที่เราต้องการอธิบายเพิ่มเติม ใส่แค่ /// (triple slash) และระบุ  tag <summary> พร้อมข้อความอธิบายสั้นๆว่า API นี้ทำอะไร (ตามภาพ) เท่านั้นเอง, ถ้าอยากยกตัวอย่างหรืออธิบายเพิ่ม สามารถใส่ <remarks> ได้ และยังมี tag อื่นๆ ที่คุณสามารถไปดูได้ที่ Customize & extend

สรุป

Swagger เป็นเครื่องมืออำนวยความสะดวกในการสร้าง API Document เพื่อลดเวลาการเขียนเอง แต่ทั้งนี้ มีเรื่องของ Security ที่ต้องป้องกันไม่ให้คนอื่นเข้ามาได้ หรือให้ดูได้เฉพาะ Development Environment เท่านั้น รวมถึง ถ้าจะให้ Document สมบูรณ์ เราก็ควรต้องเขียนโค้ดให้ถูกต้องโดยเฉพาะเรื่องของการตั้งชื่อตัวแปร ชื่อฟังก์ชั่น โมเดล ฯลฯ เพราะข้อมูลใน Document จะอ่านง่ายแค่ไหน มันสะท้อนจากโค้ดของเรานั่นเอง

—

Reference: Microsoft.com