NestJS OpenApi( Swagger )

OpenApi

ขอนิยามเองตามความเข้าใจนะครับ เป็นตัวที่อธิบาย Api ต่างๆ ของระบบที่เราสร้างเพื่อให้ติดต่อสื่อสารกับคนอื่น หรือภายใจทีม เข้าใจว่าเรามี Api อะไรบ้าง เวลาเรียก Api ต้องทำอะไรบ้าง เช่น เราเขียน Api customer ขึ้นมา เราต้องบอกรายละเอียดของ Api เราว่า ต้องแนบ token อะไร URL อะไร ต้องส่ง body ยังไง
ซึ่งมันจะง่ายกว่าไหมถ้า เรามีตัวช่วยเราในการ อธิบาย และ OpenApi ก็ช่วยเราได้เป็นอย่างดีครับ

ในบทความนี้ผมขอยกตัว อย่าง API ของ NestJs นะครับ และ OpenApi เป็น Swagger

Install

$ npm install --save @nestjs/swagger swagger-ui-express
$ npm install --save @nestjs/swagger fastify-swagger

main.ts

DocumentBuilder()
จะเป็นตัว Gen Document Api ของเราออกมา ซึ่งสามารถ Set Detail ได้มากมาย

.setTitle(‘Test Open Api’) มีไว้ระบุ ชื่อ Document
.setDescription(‘The Open API description’) มีไว้ระบุ รายละเอียด Document
.setVersion(‘1.0’) มีไว้ระบุ Vertion Document
.addTag(‘Test Open Api’) มีไว้ระบุ ว่าเราจะ Add Api ไหนลงไปที่ Document
.setSchemes(‘https’, ‘http’) มีไว้ระบุว่า Api เรานั้นสามารถ ยิงผ่าน https และ http
.addBearerAuth() หาก Api เราต้อง แนบ BearerAuth เราสามารถเพิ่ม BearerAuth เพื่อให้ผู้อ่าน Document แนบ เพื่อทุกครั้งที่เรียก Api จะต้องแนบไป
.build(); คำสั่ง Build Document

controller.ts

สิ่งที่เราต้องใช้ในการบอก swagger ให้ดึงข้อมูลไปทำ OpenApi

ApiUseTags
@ApiUseTags(‘cats’) ให้เอาไปเพิ่มตรง Class หรือ Funtion ของ Class
Tag ที่จะเอาไว้แสดงหน้า doc ดังรูป

ApiBearerAuth
@ApiBearerAuth()ให้เอาไปเพิ่มตรง Class หรือ Funtion ของ Class
Tag ซึ่งจะทำให้ทุกครั้งที่เรียก Class หรือ Funtion นั้นๆ ต้องแนบ Token Bearer มาด้วยที่จะเอาไว้แสดงหน้า doc ดังรูป

ApiResponse
@ApiResponse({status: 201,description: ‘The record has been successfully created.’,}) ให้เอาไปเพิ่มตรง Class หรือ Funtion ของ Class เพื่อที่จะบอกว่า Api เมื่อมีการ Response กลับมาแล้วจะได้ status และข้อความ อะไรกลับไปให้

ApiOperation
@ApiOperation({ title: ‘Create cat’ })
ให้เอาไปเพิ่มตรง Class หรือ Funtion ของ Class เป็น title ของ Api นั้นๆ

interface.ts

เราสามารถให้ interface ของ api เรามาเขียน เพื่อบอก ว่า api นั้นๆ ของเราจะ อะไรบ้าง
Import { ApiModelProperty } from ‘@nestjs/swagger’;
และนำ @ApiModelProperty() ไปใส่ไว้ตรงตัวแปรที่เราต้องการ

เมื่อทำการสร้างทั้งหมด แล้วลองมาดูผลกันครับว่า หน้าตาจะเป็นยังไง

สรุป
NestJs สามารถสร้าง OpenApi (Swagger) และ OpenApi นี้ยังเป็นตัวช่วยในการติดต่อสื่อสารกับ คนอื่นได้เป็นอย่างดี

อ้างอิง

Documentation | NestJS - A progressive Node.js framework