สร้าง Swagger.json ง่ายๆ ด้วย Typescript web service

ปัญหาของเว็บเซอร์วิสแบบ RESTful คือ ไม่มีรูปแบบที่แน่นอนสำหรับการใช้งาน ต้องจำทุกๆ url ทำหน้าทีอะไร มี parameter อะไร ต้องการ header ผลลัพธ์แบบใหน หากมี APIs ไม่มากจะไม่มีปัญหาอะไร แต่ถ้าเป็นโปรเจ็คใหญ่ๆ ความบรรลัยก็จะเกิดขึ้น


swagger เกิดขึ้นมาเพือกำหนดโครงสร้างของ APIs โดยสร้างการไฟล์ swagger.json ขึ้นมา แล้วสามารนำมา generate โปรเจ็คทั้งฝั่ง server และ client มาให้อัตโมัติ และรองรับเกือบทุกภาษา พร้อมกับสร้าง APIs Document ให้เลย

ปัญหาต่อมาคือ โปรแกรมเมอร์ต้องมานั่งศึกษาการเขียนไฟล์ swagger.json อีก จะดีไม่น้อย ถ้าไม่ต้องมานั่งเขียนไฟล์ swagger.json แค่เขียนฝั่ง server อย่างเดียวแล้วได้ swagger.json เลย วันนี้จะขอเสนอตัวช่วยสำหรับสร้างไฟล์ swagger.json ด้วย typescript web server

ที่มา: http://swagger.io/

สร้างเว็บเซอร์วิสเลย!

npm init -f
npm i tsoa express method-override body-parser --save
npm i typescript tsoa ts-node -gtsc --init

อย่าลืมเปิด emitDecoratorMetadata, experimentalDecorators ด้วย

ไฟล์ tsconfig.json
ไฟล์คอนฟิก tsoa.json

สร้างคลาส HelloController และสร้าเมธอด hello return ต้อง Promise เท่านั้น และกำหนดเป็นเมธอดแบบ GET ในส่วน parameter @Path บอกให้เอาค่า ‘name’ ค่าจาก path ถ้า @Query เอาค่ามาจาก querystring

ไฟล์ hello-controller.ts

หากเคยใช้ express.js มาก่อนก็สามารถนำมาใช้ได้เลย ที่สำคัณคือ 1. ต้อง import controller ที่เขียนไว้ 2. ต้อง import routes ที่ได้จากการ gen ไม่งั้น controller จะไม่ทำงาน

ไฟล์ server.ts

มา generate swagger.json กันเถอะ

tsoa swagger  // สำหรับการ generate swagger.json 
tsoa routes // สำหรับการ generate express routes

จะได้ไฟล์ swagger.json

สามารถดูเป็น document โดยเปิด Swagger UI หรือจะนำไฟล์ swagger.json มา generate client code โดยการเปิด Swagger Editor

ไฟล์ swagger.json ที่ได้

นี้เป็นบทความแรก ผิดผลาดประการใด ขออภัยด้วย