บทแนะนำ OpenAPI 3.0: 8 เคล็ดลับสำหรับการจัดทำเอกสารข้อมูลจำเพาะ API

ก่อนหน้านี้ คุณอาจจะใช้ Swagger 2.0 (หรือที่รู้จักกันในชื่อ OAS 2) แต่ตอนนี้ถึงเวลาอัปเกรดเป็น OpenAPI Specification (OAS) 3 แล้ว ในบทความนี้ เราจะสรุปประเด็นสำคัญของกระบวนการอัปเกรดและสิ่งจำเป็นในการจัดทำเอกสาร API โดยใช้ OAS 3

บางประเด็นเหล่านี้อาจยังคงใช้ได้กับเอกสาร OAS 2 (เดิมชื่อ Swagger) ก่อนหน้านี้ แต่ก็ควรค่าแก่การจดจำ เนื่องจากผมอาจจะไม่ได้เน้นย้ำถึงประเด็นเหล่านี้อย่างเต็มที่ก่อนหน้านี้

ตัวอย่างโค้ดในบทความนี้ถูกดึงมาจากข้อกำหนด OAS 3 ของ bookmarks.dev-api ซึ่งมีอยู่ในไฟล์ openapi.yaml บน GitHub สามารถดูผลลัพธ์ได้ที่ bookmarks.dev/api/docs/

นี่คือข้อควรพิจารณาหลักสิบประการ:

1. อ่านเอกสารข้อกำหนด

อ่านบทความ "A Guide to What's New in OpenAPI 3.0" ซึ่งแบ่งปันการอัปเดตที่สำคัญบางส่วนใน OAS เวอร์ชันล่าสุด และให้ข้อมูลเชิงลึกโดยละเอียดเกี่ยวกับสิ่งที่คุณจำเป็นต้องรู้เมื่อเปลี่ยนจาก OAS 2.0 เป็น OAS 3.0 บทความนี้อิงตามการสัมมนาผ่านเว็บ 1 ชั่วโมง "OpenAPI 3.0, And What it Means for the Future of Swagger"

2. ใช้บริการเว็บตัวแปลง

ใช้บริการเว็บตัวแปลง OpenAPI/Swagger 2.0 เป็น OpenAPI 3.0 เพื่อแปลงข้อกำหนด Swagger ของคุณเป็น OpenAPI 3.0

มีให้บริการออนไลน์ที่ https://converter.swagger.io/ และคุณยังสามารถใช้เป็นอิมเมจ Docker ได้:

docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2

3. ตรวจสอบความถูกต้องของข้อกำหนดของคุณและดูตัวอย่างด้วย Swagger Editor

Swagger Editor ช่วยให้คุณแก้ไขข้อกำหนด API Swagger ที่จัดรูปแบบ YAML ในเว็บเบราว์เซอร์ของคุณและดูตัวอย่างเอกสารได้ทันที

คุณสามารถใช้งานออนไลน์หรือเป็นเวอร์ชันที่เผยแพร่โดย npm หรืออิมเมจ Docker สำหรับรายละเอียดเพิ่มเติม โปรดดูที่ README ของโปรเจกต์

4. แสดงเอกสารของคุณด้วย Swagger UI

Swagger UI คือชุดทรัพยากร HTML, JavaScript และ CSS ที่สร้างเอกสารประกอบที่สวยงามสำหรับ API ที่สอดคล้องกับ Swagger แบบไดนามิก

คุณสามารถใช้งานได้โดยตรง เช่นเดียวกับผม โดยเข้าถึงเอกสาร Swagger UI ผ่านเส้นทาง API ตัวอย่างเช่น bookmarks.dev/api/docs/ นี่คือโค้ดสั้นๆ จาก app.js:

const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');

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

การรวมไฟล์ข้อกำหนดแบบเปิด (openapi.yaml) ในการตรวจสอบ nodemon ของคุณ (เช่น nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) สามารถช่วยได้ ทำให้คุณสามารถโหลด UI ใหม่ได้โดยไม่ต้องรีสตาร์ทเซิร์ฟเวอร์ ExpressJS ด้วยตนเอง

4.1. ใช้ swagger-jsdoc สำหรับแนวทาง Code-First

อีกประเด็นที่น่าสังเกตคือ คุณสามารถใช้ swagger-jsdoc เพื่อรวม Swagger ผ่านคำอธิบายประกอบ JSDoc ในโค้ดของคุณ โปรเจกต์ swagger-jsdoc ถือว่าคุณต้องการจัดทำเอกสารโค้ดที่มีอยู่ ทำงานอยู่ และใช้งานได้จริงในลักษณะที่ "เติมชีวิตชีวา" ให้กับโค้ดนั้น สร้างข้อกำหนดที่สามารถป้อนลงในเครื่องมือ Swagger อื่นๆ ได้ แทนที่จะเป็นวิธีอื่น

ปัจจุบัน ผมจัดการเอกสารในไฟล์ openapi.yaml ไฟล์เดียว แต่ผมอาจพิจารณาใช้ในอนาคต

5. จัดกลุ่มการดำเนินการโดยใช้ Tags

คุณสามารถกำหนดรายการ tag ให้กับการดำเนินการ API แต่ละรายการ ทำให้ Swagger UI และ Swagger Editor แสดงการดำเนินการตาม tags ได้อย่างสะดวก ในการควบคุมการเรียงลำดับใน Swagger UI คุณต้องเพิ่ม tags เหล่านั้นเป็น tags ส่วนกลางที่ระดับรูท คุณยังสามารถเพิ่มคำอธิบายและลิงก์ไปยังเอกสารภายนอกได้ที่นั่น

นี่คือ tags ที่ผมใช้สำหรับ API:

yamlCopy code
tags:- name: rootdescription: Used to mark root endpoints- name: versiondescription: Access project version and gitSha1- name: public-bookmarksdescription: Access public bookmarks- name: personal-bookmarksdescription: Operations on personal bookmarks- name: user-datadescription: Operations on user data- name: helperdescription: Helper endpoints/operations

6. ระบุ URL พื้นฐานของ API ด้วย Servers

ใน OpenAPI 3.0 คุณใช้ array servers เพื่อระบุ URL พื้นฐานอย่างน้อยหนึ่งรายการสำหรับ API Servers แทนที่คำหลัก host, basePath และ schemes ที่ใช้ใน OpenAPI 2.0 เซิร์ฟเวอร์แต่ละตัวมี URL และคำอธิบายเสริมในรูปแบบ Markdown

yamlCopy code
servers:- url: http://localhost:3000/apidescription: Local server for development- url: https://www.bookmarks.dev/apidescription: Main (production) server

7. กำหนดและนำทรัพยากรกลับมาใช้ใหม่ด้วย Components

บ่อยครั้ง การดำเนินการ API หลายรายการใช้พารามิเตอร์ทั่วไปร่วมกัน หรือส่งคืนโครงสร้างการตอบสนองแบบเดียวกัน เพื่อหลีกเลี่ยงการทำซ้ำโค้ด คุณสามารถวางคำจำกัดความทั่วไปในส่วน components ส่วนกลางและอ้างอิงโดยใช้ $ref

ตัวอย่างเช่น สำหรับการตอบสนองทั่วไปสำหรับการดำเนินการหลายรายการที่รายการบุ๊กมาร์กปรากฏขึ้น ผมกำหนด BookmarkListResponse ภายใต้ components > responses:

components:responses:BookmarkListResponse:description: List of bookmarkscontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"

จากนั้น ผมอ้างอิงในการดำเนินการต่างๆ เช่น get-public-bookmarks:

yamlCopy code
/public/bookmarks:get:summary: Return a list of public bookmarks using query parameters.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"

โปรดทราบ locationQueryParam ที่กล่าวถึงข้างต้น กำหนดไว้ภายใต้ components > parameters และอ้างอิงในหลายๆ ที่ในข้อกำหนด API รวมถึงตัวอย่างที่แสดงด้านบน

8. เพิ่มตัวอย่างเพื่อความชัดเจน

คุณสามารถเพิ่มตัวอย่างให้กับพารามิเตอร์ คุณสมบัติ และอ็อบเจกต์เพื่อให้ข้อกำหนดของ Web service ของคุณชัดเจนยิ่งขึ้น เครื่องมือและไลบรารีต่างๆ สำหรับ API ของคุณสามารถอ่านตัวอย่างได้ ตัวอย่างเช่น เครื่องมือ API จำลองสามารถใช้ค่าตัวอย่างเพื่อสร้างคำขอจำลอง คุณสามารถระบุตัวอย่างสำหรับอ็อบเจกต์ คุณสมบัติแต่ละรายการ และพารามิเตอร์การดำเนินการโดยใช้คีย์ example หรือ examples

ตัวอย่างเช่น คุณสามารถมีค่าที่ซับซ้อนเป็นตัวอย่างสำหรับพารามิเตอร์ข้อความค้นหา:

components:parameters:searchTextQueryParam:name: qin: querydescription: |
        Search query (words separated by spaces). Special filters available:
          * `lang:iso_language_code` - e.g., `lang:en` for English, `lang:es` for Spanish, `lang:de` for German bookmarks
          * `site:site_URL` - e.g., return bookmarks from [www.codepedia.org](htt