บทแนะนำ OpenAPI 3.0: คำจำกัดความของ OpenAPI Specification

คุณต้องการความช่วยเหลือในการพัฒนาและจัดทำเอกสาร API สำหรับโครงการขนาดใหญ่หรือซับซ้อนหรือไม่? ไม่ต้องกังวล! เรามีวิธีแก้ปัญหาสำหรับคุณ - OpenAPI Specification (เดิมชื่อ Swagger Specification) มาตรฐานโอเพนซอร์สฟรีนี้ทำให้การพัฒนาและจัดทำเอกสาร API เป็นเรื่องง่าย! ด้วย OpenAPI คุณสามารถสร้างและจัดทำเอกสาร API ได้อย่างง่ายดายโดยใช้รูปแบบมาตรฐานที่เข้าใจง่าย

ประหยัดเวลาในการพยายามคิดค้นการพัฒนาและจัดทำเอกสาร API ที่ซับซ้อน ให้เราช่วยคุณลดความซับซ้อนของกระบวนการด้วย OpenAPI!

OpenAPI Specification (OAS) คืออะไร

OpenAPI คือข้อกำหนดที่กำหนดโครงสร้างของ RESTful API และอธิบายความสามารถของ API นั้น OpenAPI Specification มอบ วิธีมาตรฐาน ในการจัดทำเอกสารและโต้ตอบกับ API ทำให้ผู้พัฒนาสามารถค้นพบและทำความเข้าใจวิธีการทำงานได้อย่างมีประสิทธิภาพ RESTful API ใช้โปรโตคอล HTTP สำหรับการส่งข้อมูล ทำให้แพลตฟอร์มและระบบที่เขียนด้วยภาษาโปรแกรมต่างๆ สามารถสื่อสารกันได้ง่าย

ด้วย OpenAPI คุณไม่จำเป็นต้องเข้าถึงซอร์สโค้ดหรือการตรวจสอบการรับส่งข้อมูลเครือข่ายเพื่อทำความเข้าใจวิธีการทำงานของ API คำจำกัดความ API นั้นให้ข้อมูลทั้งหมดที่คุณต้องการ

รูปแบบ OpenAPI

OpenAPI เวอร์ชันล่าสุดคือ 3.0 คำจำกัดความ OpenAPI สามารถเขียนได้ในรูปแบบ JSON หรือ YAML JSON แสดงข้อมูลโดยใช้คู่คีย์-ค่า แทนที่จะเขียนคำอธิบาย API ที่ยาวเหยียดและทำตามโครงสร้าง OpenAPI ทำให้ง่ายต่อการทำความเข้าใจความสามารถของ API แม้ว่าคุณจะไม่มีสิทธิ์เข้าถึงซอร์สโค้ดหรือเอกสารประกอบก็ตาม

ตัวอย่าง OpenAPI 3.0 specification ในรูปแบบ JSON:

{
  "openapi": "3.0.0",
  "info": {
    "title": "API Title",
    "description": "API Description",
    "version": "1.0.0"
  }
}
}

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

ในขณะที่ JSON เป็นรูปแบบมาตรฐานสำหรับ OpenAPI คุณยังสามารถใช้ YAML ซึ่งเป็นภาษา markup ที่ตรงไปตรงมามากขึ้น ทำให้ง่ายต่อการสร้างและแก้ไขเอกสาร OpenAPI

openapi: 3.0.0
info:
  title: API Title
 
 description: API Description
  version: 1.0.0

ดังนั้นคุณก็มีพื้นฐานของ OpenAPI มันอาจดูค่อนข้างเทคนิคในตอนแรก แต่เมื่อคุณเข้าใจแล้ว คุณจะสงสัยว่าคุณเคยใช้ชีวิตอยู่ได้อย่างไรหากไม่มีมัน

The OpenAPI specification ใช้ชนิดข้อมูล JSON ที่กำหนดไว้ใน JSON Schema Specification ชนิดข้อมูลเหล่านี้รวมถึงจำนวนเต็ม ตัวเลข บูลีน และสตริง คุณยังสามารถปรับเปลี่ยนรูปแบบของชนิดข้อมูลเหล่านี้ได้โดยใช้คุณสมบัติ 'format' เช่น int32, int64, float, double, binary, data, date-time และรูปแบบรหัสผ่าน OpenAPI ยังอนุญาตให้ใช้โมเดล (อ็อบเจกต์) ที่กำหนดภายใต้ข้อกำหนด JSON เป็นอ็อบเจกต์ schema

โครงสร้าง OpenAPI

OpenAPI specification คือเอกสารที่อธิบายโครงสร้างและพฤติกรรมของ REST API มาเจาะลึกเอกสาร OpenAPI กัน

เอกสาร OpenAPI มีรูปแบบที่มีโครงสร้างซึ่งประกอบด้วยอ็อบเจกต์หรืออาร์เรย์ของอ็อบเจกต์ที่จัดกลุ่มคู่คีย์-ค่าที่เกี่ยวข้อง วงเล็บเหลี่ยมชุดแรก {} ในเอกสาร OpenAPI มีคุณสมบัติทั้งหมดและเรียกว่า "document object" แม้ว่าจะมีความยืดหยุ่นอยู่บ้าง แต่เอกสาร OpenAPI ต้องเป็นไปตามโครงสร้างพื้นฐาน บางส่วนระดับสูงเป็นข้อบังคับ ในขณะที่ส่วนอื่นๆ เป็นตัวเลือก ทำให้เกิดความแตกต่างใน OpenAPI specs ใน API ที่แตกต่างกัน

เอกสาร OpenAPI อาจมีส่วนต่างๆ ดังต่อไปนี้:

• OpenAPI: API ต้องมีข้อกำหนดของเวอร์ชัน OpenAPI เพื่อให้เครื่องมือสามารถแยกวิเคราะห์ OpenAPI specification และสร้างเอกสารประกอบได้
• Info: ฟิลด์นี้มีข้อมูลเมตาเกี่ยวกับ API เช่น ชื่อเรื่อง คำอธิบาย และเวอร์ชัน เครื่องมือต่างๆ สามารถใช้ประโยชน์จากข้อมูลนี้ได้
• Servers: ฟิลด์นี้ใน OpenAPI Specification ประกอบด้วยอาร์เรย์ของอ็อบเจกต์เซิร์ฟเวอร์ ซึ่งแต่ละรายการมี URL สำหรับโฮสต์เซิร์ฟเวอร์และคำอธิบายสั้นๆ เกี่ยวกับเซิร์ฟเวอร์ ข้อมูลนี้ให้รายละเอียดการเชื่อมต่อที่คุณสามารถใช้เพื่อโต้ตอบกับเซิร์ฟเวอร์ได้
• Paths: อ็อบเจกต์นี้มีเส้นทางสัมพัทธ์ไปยังปลายทางแยกต่างหากของ API แต่ละเส้นทางมี operation ที่พร้อมใช้งานสำหรับการโต้ตอบกับ API เช่น POST, GET, PUT หรือ DELETE
• Components: ฟิลด์นี้ใน OpenAPI Specification เป็นอ็อบเจกต์ที่มี schemas ที่นำกลับมาใช้ใหม่ได้สำหรับเนื้อหาคำขอ, schemas การตอบสนอง และ security schemes schemas เหล่านี้สามารถอ้างอิงได้ตลอดทั้ง spec โดยใช้แท็ก $ref โดยเฉพาะอย่างยิ่งในอ็อบเจกต์ path
• Security: อ็อบเจกต์ที่ประกาศประเภทของ security scheme ที่อนุญาตคำขอ อ็อบเจกต์ security ถูกกำหนดไว้ทั่วโลกหรือถูกแทนที่โดย operation แต่ละรายการ
• Tags: อ็อบเจกต์ที่มีข้อมูลเมตาที่ระบุลำดับที่คุณควรแสดงทรัพยากร API ในเอกสารประกอบ
• ExternalDocs: อ็อบเจกต์ที่เชื่อมโยงไปยังเอกสารประกอบเพิ่มเติม เช่น คู่มือผู้ใช้

นี่คือเทมเพลตพื้นฐานสำหรับเอกสาร OpenAPI พร้อมฟิลด์ที่จำเป็นในรูปแบบ YAMLJSON

คำขอ POST

ตัวอย่างปลายทางต่อไปนี้สำหรับ คำขอ POST สำหรับการอัปโหลดรูปภาพของสัตว์เลี้ยงถูกกำหนดไว้

openapi: 3.0.3
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.11
servers:
  - url: https://petstore3.swagger.io/api/v3
tags:
  - name: pet
    description: Everything about your Pets

paths:
  /pet/{petId}/uploadImage:
    post:
      tags:
        - pet
      summary: uploads an image
      description: ''
      operationId: uploadFile
      parameters:
        - name: petId
          in: path
          description: ID of pet to update
          required: true
          schema:
            type: integer
            format: int64
        - name: additionalMetadata
          in: query
          description: Additional Metadata
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: successful operation

คุณสามารถเรียกใช้โค้ดสnippet ด้านบนได้ที่ https://editor.swagger.io/ ผลลัพธ์จะเป็นดังนี้

โค้ดสnippet เริ่มต้นด้วยการให้ข้อมูลพื้นฐานเกี่ยวกับ API เช่น ชื่อเรื่องและเวอร์ชัน นอกจากนี้ยังระบุ URL พื้นฐานสำหรับเซิร์ฟเวอร์ API

ส่วน tags กำหนดแท็กชื่อ "pet" ที่จัดกลุ่มปลายทางทั้งหมดที่เกี่ยวข้องกับสัตว์เลี้ยง ส่วน paths มีคำจำกัดความสำหรับปลายทาง /pet/{petId}/uploadImage

ปลายทาง /pet/{petId}/uploadImage รองรับเมธอด POST เพื่ออัปโหลดรูปภาพสำหรับสัตว์เลี้ยง ส่วน parameters กำหนดพารามิเตอร์สองตัว "petId" และ "additionalMetadata" ซึ่งระบุ ID สัตว์เลี้ยงที่จะอัปเดตและข้อมูลเมตาเพิ่มเติมสำหรับรูปภาพที่อัปโหลดตามลำดับ

ส่วน request body ระบุโครงสร้างของ request body ซึ่งคาดว่าจะอยู่ในรูปแบบไบนารี ส่วน responses กำหนดรหัสการตอบสนองเดียว 200 ซึ่งบ่งชี้ถึงการดำเนินการที่สำเร็จ

OpenAPI มีประโยชน์อย่างไร

OpenAPI Specification มอบประโยชน์หลายประการสำหรับนักพัฒนาที่สร้างและจัดทำเอกสาร API

OpenAPI Specification ปรับปรุงการพัฒนา API ผ่านการทำงานร่วมกันที่ดีขึ้น ความสอดคล้อง การสร้างโค้ด การตรวจสอบความถูกต้อง และเครื่องมือ วิธีมาตรฐานและโปร่งใสในการอธิบาย API ช่วยลดความสามารถของทีมในการทำงานร่วมกันอย่างมีประสิทธิภาพในขณะที่รับประกันความสอดคล้องในเอกสารประกอบ API

นักพัฒนาสามารถสร้างโค้ดสำหรับ API ในภาษาโปรแกรมหลายภาษา รักษาความสอดคล้องในทุกภาษา ไฟล์เอกสารประกอบที่สร้างขึ้นมีความน่าเชื่อถือและสอดคล้องกันในขณะเดียวกันก็ช่วยประหยัดเวลาสำหรับนักพัฒนา

เครื่องมือตรวจสอบความถูกต้องช่วยรับประกันความเข้ากันได้และป้องกันข้อผิดพลาด ในขณะที่ระบบนิเวศของเครื่องมือที่หลากหลายช่วยปรับปรุงกระบวนการพัฒนา API ทั้งหมด OpenAPI Specification ลดข้อผิดพลาดและปรับปรุงคุณภาพของโครงการซอฟต์แวร์ที่เกิดขึ้น

วิธีการสร้าง OpenAPI Specification

แต่จะเกิดอะไรขึ้นถ้าคุณต้องการหลีกเลี่ยงการเขียนโค้ดด้วยตนเอง? ไม่ต้องกังวล เราพร้อมช่วยเหลือ!  Apidog เป็นเครื่องมือที่ทำให้การทำงานกับ OpenAPI Specification เป็นเรื่องง่าย  เป็นแพลตฟอร์มบนคลาวด์ที่ช่วยลดความซับซ้อนในการออกแบบ ทดสอบ และเผยแพร่ API ด้วยวิธีนี้ นักพัฒนาสามารถสร้างและแก้ไข OpenAPI specifications โดยใช้ตัวแก้ไขภาพที่ใช้งานง่าย

Apidog ยังมีเครื่องมือทดสอบในตัวที่ช่วยให้นักพัฒนาสามารถทดสอบ API ของตนได้โดยตรงจากแพลตฟอร์ม  มีตลาด API ที่นักพัฒนาสามารถค้นพบและใช้ API ที่สร้างไว้ล่วงหน้าจากนักพัฒนาคนอื่นๆ ด้วยวิธีนี้ คุณสามารถเพิ่ม paths, parameters และ responses ให้กับ API ของคุณได้อย่างรวดเร็วโดยใช้อินเทอร์เฟซที่ใช้งานง่าย

ส่วนที่ดีที่สุด? Apidog สร้างเอกสารประกอบโดยอัตโนมัติ ด้วยการคลิกเพียงไม่กี่ครั้ง คุณสามารถสร้างเอกสารประกอบที่สวยงามสำหรับ API ของคุณตาม OpenAPI specification เอกสารประกอบประกอบด้วยข้อมูลเกี่ยวกับแต่ละปลายทาง รวมถึงพารามิเตอร์ การตอบสนอง และตัวอย่าง

มาดูคำแนะนำทีละขั้นตอนเกี่ยวกับวิธีที่เราสามารถทำได้ นี่คือกระบวนการทีละขั้นตอนในการนำเข้าไฟล์ OpenAPI specification ลงใน Apidog:

ขั้นตอนที่ 1. เปิดเว็บไซต์ Apidog

ขั้นแรก เปิดเว็บไซต์ Apidog ในเว็บเบราว์เซอร์ของคุณ คุณสามารถเข้าถึงได้โดยไปที่ เว็บไซต์ ของพวกเขา

ขั้นตอนที่ 2. เข้าสู่ระบบบัญชีของคุณ

หากคุณมีบัญชี API Dog อยู่แล้ว ให้ลงชื่อเข้าใช้โดยคลิกปุ่ม "Sign In" ที่มุมขวาบนของหน้า หากคุณไม่มีบัญชี คุณสามารถสร้างบัญชีได้โดยคลิกปุ่ม "Sign Up" และทำตามคำแนะนำ

ขั้นตอนที่ 3. สร้างโปรเจกต์ใหม่

เมื่อลงชื่อเข้าใช้แล้ว ให้คลิกปุ่ม "Create Project" เพื่อสร้างโปรเจกต์ใหม่

ขั้นตอนที่ 4. นำเข้าไฟล์ OpenAPI

นำเข้าไฟล์ OpenAPI specification ในหน้าสร้างโปรเจกต์ คลิกปุ่ม "Import" เพื่อดำเนินการต่อ

ขั้นตอนที่ 5. อัปโหลดไฟล์ OpenAPI ของคุณ:

ในหน้าการนำเข้า คุณจะเห็นช่องที่คุณสามารถ ป้อน URL ของไฟล์ OpenAPI ของคุณได้ หากคุณไม่มี URL คุณสามารถอัปโหลดไฟล์จากเครื่องในพื้นที่ของคุณได้โดยคลิกตัวเลือก "or upload a file" และเลือกไฟล์

ป้อน URL ของไฟล์ JSON ของฉัน

ขั้นตอนที่ 6. รอให้การนำเข้าเสร็จสมบูรณ์

ขึ้นอยู่กับขนาดและความซับซ้อนของไฟล์ OpenAPI ของคุณ กระบวนการนำเข้าอาจใช้เวลาสองสามนาที

Apidog จะแยกวิเคราะห์ไฟล์โดยอัตโนมัติและสร้าง API ใหม่ในบัญชีของคุณ

ขั้นตอนที่ 7. กำหนดค่าการตั้งค่า API ของคุณ

หลังจากนำเข้าไฟล์ OpenAPI แล้ว จะนำคุณไปยังหน้าการตั้งค่าสำหรับ API ใหม่ของคุณ คุณสามารถกำหนดค่าการตั้งค่าต่างๆ ในหน้านี้ เช่น ชื่อ คำอธิบาย และข้อกำหนดการตรวจสอบสิทธิ์ของ API ของคุณ

ขั้นตอนที่ 8. เริ่มสร้าง API ของคุณ

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

ด้วยการทำตามขั้นตอนง่ายๆ ในการนำเข้าไฟล์ OpenAPI specification ลงใน Apidog คุณสามารถจัดการและจัดทำเอกสารโครงการ API ของคุณได้อย่างมีประสิทธิภาพมากขึ้น ไฟล์ specification โดยทั่วไปจะมีรายละเอียดที่จำเป็น เช่น ปลายทาง POST, path, parameters และ response codes

หลังจากเพิ่มไฟล์ specification ของคุณลงใน Apidog คุณสามารถใช้ประโยชน์จาก API ที่ใช้งานง่ายและเครื่องมืออันทรงพลังเพื่อรับประกันความสอดคล้องและความน่าเชื่อถือในกระบวนการพัฒนา API ของคุณ ดังนั้น หากคุณต้องการประหยัดเวลาและปรับปรุงกระบวนการพัฒนา API ของคุณ ให้พิจารณาใช้ OpenAPI Specification กับ Apidog