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

by | 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 ผลลัพธ์สุดท้ายที่ได้

https://apidocjs.com/example_basic/

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();

คำสั่งใช้สร้างเว็บ apidoc

apidoc -i src/ -o public/apidoc

หลังจากรันคำสั่งเสร็จ จะมี folder ชื่อ apidoc ใน pubilc ในโปรเจคเรา ซึ่งในนั้นมีไฟล์ต่างๆ เป็นรูปแบบ static website

วิธีเข้าถึงเว็บ

localhost:9090/apidoc

*ข้อควรระวัง

ความแตกต่างของ os เมื่อสั่ง generate apidoc ให้ตรวจเช็คดู path เพราะการเข้าถึงไฟล์ต่างกัน ตัวอย่างที่แชร์ใน post นี้รันบน macOS

*** apidoc ให้เราจัดเรียงกลุ่มของ API และแสดงวิธีการเข้าถึงแต่ละ API ออกมาเป็นแบบ side bar ช่วยให้เราที่เป็น backend และ frontend ดูง่าย และดีต่อใจ

ข้อมูลที่เกี่ยวข้อง

https://apidocjs.com/#getting-started

บทความที่เกี่ยวข้อง

เบื้องหลังการเปลี่ยน Authentication เว็บไซต์จาก Token-based มาเป็น Session-Based

เบื้องหลังการเปลี่ยน Authentication เว็บไซต์จาก Token-based มาเป็น Session-Based

นักพัฒนาก่อนจะลงมือสร้างฟีเจอร์ของระบบ จะต้องมีการเช็คบัญชีของผู้ใช้และสิทธิการเข้าถึง วิธีการมีหลายรูปแบบ...

read more