Start using Swagger in Nodejs

Swagger เป็น tools ที่นักพัฒนาใช้กันเยอะมาก และเราใช้ Swagger ในการทำ Document API หรือ Test API และใน Part นี้จะมานำเสนอการใช้ Swagger ร่วมกับ Nodejs กัน

ติดตั้ง Package ที่เราจะใช้กัน

npm init -y // เพื่อสร้างไฟล์ package.json

npm install --save swagger-ui-express  yamljs express // 3 package ที่เราจะใช้ในการทำครั้งนี้

ขั้นตอนต่อมาให้เราเตรียม ไฟลล์ swagger.yaml  ซึ่งจะเป็นที่เก็บค่า config document api ของเรายกตัวอย่าเช่น path  /user/:id จะต้องส่ง parameter อะไรบ้าง เป็น number หรือ string และใช้ get, post, put, delete
 

แนะนำ https://editor.swagger.io/ สำหรับตัวอย่างสร้าง swagger.yaml

const express = require('express');
const app = express()
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const swaggerDocument = YAML.load('./swagger.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3001, ()=> { console.log('running')})

นี้ก็เป็นตัวอย่างไฟลล์งานของผมครับ คือการเรียกใช้งาน swagger-ui-express มาใช้งาน และก็โหลดไฟลล์ swagger.yaml เพื่อมาใช้ร่วมกับตัว swagger-ui-express สุดท้ายเราก็ทำ export ผ่าน route /api-docs จากนั้นก็ run ตัว node ของเรา

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in HTML.
  version: 0.1.9
servers:
  - url: https://api.opendota.com/api
    description: test from https://docs.opendota.com/
paths:
  /playersByRank:
    get:
      summary: Player By Rank.
      description: Player By Rank.
      responses:
        '200':    # status code
          description: List of Player
          content:
            application/json:
              schema: 
                type: array

นี้คือตัวไฟลล์ swagger ที่ผมยกตัวอย่าง ผมนำ api ของ opendota มาทดลองยิงดูครับ ซึ่ง base url ของผมคือ https://api.opendota.com/api จากนั้นผมก็มาเขียนจะไปเรียก path ไหนบ้างซึ่งผมยกตัวอย่างไว้คือ /playersByRank

สำหรับงานผม https://github.com/najaroen/swagger-nodejs-me

สรุปการใช้ swagger ก็เป็นหนึ่งในตัวเลือกการทำ API Document ครับซึ่งจำเป็นมากๆ ครับเพราะทำให้เราทำงานร่วมกับคนอื่นที่จะนำ API ของเราไปใช้งาน ทำงานได้ง่ายขึ้น และลดเวลาการทำงานด้วยครับ ซึ่งตัวอย่างเพิ่มเติมสามารถเข้าไปดูใน https://swagger.io/ ขอบคุณสำหรับทุกคนที่เข้ามาอ่านด้วยนะครับหวังว่าจะเป็นประโยชน์นะครับ