สร้าง API Doc ด้วยการใส่ comment ในโค้ด nodejs

by Jirayuth Sing-ngam | Last updated Jun 4, 2020 | DEVELOPERS | 0 comments

หลังจากที่ developer ฝั่งหลังบ้านสู้ทนนั่งหลังขดหลังแข็ง implement แต่ละฟีเจอร์จนเสร็จเป็นที่เรียบร้อย จะมีอีกหนึ่งงานที่เหล่า backend ต้องทำนั่นคือการเขียน API Doc ซึ่งถือได้ว่าเป็นงานที่เร่งด่วนพอตัว

ประสบการณ์ได้เคยลองใช้ postman แต่ก็รู้สึกหงุดหงิดที่ให้ต้องเขียนเป็นภาษา markdown และวุ่นวายกับการพิมพ์ข้อความที่ยังไม่รองรับภาษาไทย และปัจจัยอื่นเล็ก ๆ น้อย ๆ

การค้นพบของ library ที่ชื่อว่า apidoc ทำให้ชีวิตได้พบเจอคำตอบ บอกได้เลยว่าตอบโจทย์

วิธีการสร้าง API Doc นั้นง่าย เพียงให้เราเพิ่ม comment ตรงไหนก็ได้ในโปรเจค แล้วก็ป้อนคำสั่งให้ระบบมัน generate เอกสารของ API Doc Spec ออกมาแสดงให้เราเป็นเว็บไซต์

Example ผลลัพธ์สุดท้ายที่ได้

Example ของ comment ที่เขียนไว้ในโค้ดเรา

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

วิธีการนำมาใช้กับ expressjs ของ nodejs

// src/app.ts

class App {
  public app: express.Application;
  public port = process.env.PORT || 9090;

  constructor() {
    this.app = express();
    this.initializeMiddlewares();
  }

  public listen() {
    this.app.listen(this.port, () => {
      console.log(`🚀 App listening on the port ${this.port}`);
    });
  }

  private initializeMiddlewares() {
    this.app.use(express.static(path.join(__dirname, "..", "public")));
  }
}

//สร้าง server
const app = new App();

app.listen();