Screenshot from 2016-07-30 13-49-55 Cropped

บทความนี้เราขอแนะนำการใช้งาน swagger-ui ซึ่งในการทำเอกสารสำหรับ Restful API ที่น่าใช้งานพร้อมทั้งสามารถทำการทดสอบผลการทำงานของ API ได้ โดยที่เราไม่ต้องทำหน้า UI สำหรับเอกสารของ API ขึ้นมาเองทั้งหมดช่วยประหยัดเวลาในการพัฒนา และด้วยโครงสร้างในการทำเอกสาร swagger-ui ยังมาพร้อมระบบที่รองรับการทดสอบ API ได้ด้วย

การใช้งาน swagger-ui สำหรับทำเอกสาร Restful API

ในโครงการของ swagger.io มีหลายๆส่วนที่เกี่ยวข้องการ การทำ api documentation แต่สำหรับนักพัฒนาที่จำเป็นต้องใช้งานเอกสาร api อย่างเร่งด่วน โดยที่ไม่ต้องเริ่มคิดว่าจะทำเอกสารให้ผู้ที่จะนำ api ไปใช้งานต่ออย่างไร แนะนำให้เริ่มต้นจาก swagger-ui

Screenshot from 2016-07-30 14-52-52 Cropped

Download swagger-ui

  1. ดาวน์โหลด Swagger-UI 2.1.0 ได้ที่ https://github.com/swagger-api/swagger-ui/archive/v2.1.0.tar.gz
  2. แตกไฟล์ zip เพื่อใช้งานใน folder dist
  3. นำไปรันบน webserver

แก้ไขไฟล์ index.html เพื่อโหลดไฟล์ swagger json

สร้างไฟล์ swagger json format เพิ่มไปในรายการ list box

{
 "swagger" :"2.0",
 "info" : {
 "title" : "OHM Search Engine API",
 "description" : "",
 "version" : "1.0.0"
 },
 "host" : "ohm.unixdev.co.th",
 "basePath" : "/api",
 "tags" : [
 {
 "name" : "search",
 "description" : "search function"
 }
 ],
 "schemes" : ["http"],
 "paths" : {
 "/autocomplete/search/{query}" : {
 "get" : {
 "tags" : ["search"],
 "summary" : "",
 "description" : "",
 "operationId" : "autocompleteSearchQuery",
 "produces" : ["application/json"],
 "parameters" : [
 {
 "name" : "query",
 "in" : "path",
 "description": "query string a path of word",
 "required" : true,
 "type" : "string"
 }
 ],
 "responses" : {
 "200" : {
 "description" : "successful operation",
 "schema" : {
 "$ref" : "#/definitions/Word"
 }
 }
 }
 }
 }
 },
 "definitions" : {
 "Word" : {
 "type" : "array",
 "items" : {
 "type" : "string"
 }
 }
 }
}

ส่วนของรายละเอียดเกี่ยวกับเอกสาร

 "info" : {
 "title" : "OHM Search Engine API",
 "description" : "",
 "version" : "1.0.0"
 },

ส่วนของ api path url และ tag

 "host" : "ohm.unixdev.co.th",
 "basePath" : "/api",
 "tags" : [
 {
 "name" : "search",
 "description" : "search function"
 }
 ],
 "schemes" : ["http"],

ส่วนที่เกี่ยวข้องกับ path ของ api

 "paths" : {
 "/autocomplete/search/{query}" : {
 "get" : {
 "tags" : ["search"],
 "summary" : "",
 "description" : "",
 "operationId" : "autocompleteSearchQuery",
 "produces" : ["application/json"],
 "parameters" : [
 {
 "name" : "query",
 "in" : "path",
 "description": "query string a path of word",
 "required" : true,
 "type" : "string"
 }
 ],
 "responses" : {
 "200" : {
 "description" : "successful operation",
 "schema" : {
 "$ref" : "#/definitions/Word"
 }
 }
 }
 }
 }
 },

ส่วนที่เกี่ยวข้องกับการกำหนดรูปแบบของผลการ response

 "definitions" : {
 "Word" : {
 "type" : "array",
 "items" : {
 "type" : "string"
 }
 }
 }

ดูตัวอย่างการทำงานของ api ได้ที่ http://petstore.swagger.io/

สำหรับรายละเอียดในการกำหนด specification ดูได้ที่ http://swagger.io/specification/