OpenAPI to TypeScript Converter: แปลง API Spec เป็น TypeScript Interface ในเบราว์เซอร์

ถ้าคุณเคยเรียก REST API จากโปรเจกต์ TypeScript คงคุ้นเคยกับฉากนี้ดี ทีม backend ส่งเอกสาร OpenAPI มาให้ คุณเปิด editor แล้วเริ่มเขียน interface สำหรับ request และ response ที่วางแผนจะใช้ทีละตัวด้วยมือ รู้สึก productive ได้ราวสิบนาที แล้ว API เปลี่ยน spec เปลี่ยนตาม และ interface User ที่คุณพิถีพิถันก็เริ่มโกหกคุณเงียบ ๆ OpenAPI to TypeScript Converter ปิดฉากงานแบบนั้น: paste spec ทั้งแบบ JSON หรือ YAML แล้วรับ TypeScript interface และ endpoint types ที่สะอาดภายในไม่กี่วินาที โดยทำงานทั้งหมดในเบราว์เซอร์ของคุณ

API types ที่เขียนมือแทบจะเลี่ยงไม่ได้เลยที่จะคลาดเคลื่อนจาก specification ฝั่ง server เปลี่ยนชื่อ field, flag nullable ถูกพลิกค่า หรือมี enum value ใหม่ขึ้นมา แต่ interface ใน codebase ของคุณยังอธิบาย API ที่ไม่มีอยู่แล้ว ส่วน types ที่ generate ตรงจาก spec จะไม่คลาดเคลื่อน เพราะมันอ่านจาก single source of truth ณ ตอนที่คุณ generate เมื่อ spec เปลี่ยน คุณแค่ regenerate แล้วให้ compiler ชี้ให้เห็นทุกบรรทัดของโค้ดฝั่ง client ที่โดนกระทบ

ในคู่มือนี้คุณจะได้รู้จักว่า converter ทำอะไรบ้าง components/schemas ของ OpenAPI แปลงไปเป็น construct ของ TypeScript อย่าง union, intersection และ index signature ได้อย่างไร และวิธีหลอมรวม generated types เข้าไปใน workflow ประจำวัน — ทั้งหมดนี้โดยไม่ต้องติดตั้ง CLI ไม่ต้องตั้งค่า build step และไม่ต้องส่ง API contract ของคุณขึ้น server remote

ทำไมต้องใช้ OpenAPI to TypeScript Converter?

• types ที่ไม่มีวันคลาดเคลื่อนจาก spec converter อ่าน components/schemas และส่วน paths โดยตรง แล้วปล่อย interface ที่สะท้อนมันแบบตรงตัว สเปกบอกอะไรคุณได้อย่างนั้น — ไม่มีชั้นแปลภาษาแห่งความหวังดีคั่นกลางระหว่าง contract กับโค้ด
• setup เป็นศูนย์ ไม่มี package ให้ติดตั้ง ไม่มี config file ให้ปรับ และไม่ต้องต่อ CI job เพียงเพื่อแอบดูว่า schema หนึ่งตัวจะหน้าตาเป็น TypeScript แบบไหน เปิดหน้าเว็บ paste เอกสาร แล้วอ่านผลลัพธ์
• เป็นส่วนตัวตั้งแต่การออกแบบ การประมวลผลเกิดขึ้นในเบราว์เซอร์ 100% ด้วย parser ทั้ง YAML และ JSON ที่รันแบบ local API contract ภายในองค์กร, specification ของ partner หรืออะไรที่อยู่ภายใต้ NDA จึงไม่มีทางออกจากเครื่องคุณ
• รับได้ทุกงานที่ทีมเขียนจริง เอกสาร Swagger 2.0, OpenAPI 3.0 และ 3.1, JSON ที่จัดรูปสวยงาม, JSON บรรทัดเดียวกอดกัน และ YAML ตามสไตล์ ผ่านหมด paste อะไรก็ได้ตามที่ tooling ของคุณปล่อยออกมา
• feedback loop ทันที เพราะเครื่องมืออยู่ห่างแค่การ paste ครั้งเดียว มันจึงเหมาะมากตอนออกแบบ schema: ร่าง schema, แปลง, มอง interface ที่ได้ แล้วถามตัวเองว่านี่ใช่ API ที่คุณอยาก publish จริงหรือเปล่า
• ฟรีและไม่จำกัด ไม่ต้องสมัคร ไม่มี quota ไม่มีตราน้ำติดผลลัพธ์ copy โค้ดที่ generate ได้แล้วไปต่อ

คุณสมบัติเด่น

มีรายละเอียดสามจุดที่น่าสนใจ อย่างแรก recursion สำคัญมาก: schema User ที่อ้างถึง schema Address จะได้ interface ทั้งคู่พร้อมการเชื่อม reference เรียบร้อย ไม่ใช่ก้อน field ที่ถูก flatten จนซ้ำซ้อน อย่างที่สอง endpoint types มักมีค่ามากกว่า schema interface เสียอีก เพราะมันจับรูปร่างของ response จาก GET /users/{id} และ request body ของ POST /orders โดยที่คุณไม่ต้องไล่อ่านจากเอกสารร้อยแก้ว อย่างที่สามเนื่องจาก parse ในเครื่อง แม้แต่ spec ขนาด 2MB ก็แปลงเสร็จในเวลาไม่ถึงวินาที

วิธีการใช้งาน

1. เปิด OpenAPI to TypeScript Converter ในเบราว์เซอร์ ไม่ต้องมีบัญชีและไม่ต้องติดตั้งอะไร
2. paste spec ลงช่อง input หรือลากไฟล์ .json, .yaml หรือ .yml มาวาง เครื่องมือตรวจจับรูปแบบเองแล้ว parse ให้
3. ดูเอกสารที่ตรวจพบ: tool จะแสดงรายการ schema ที่เจอใต้ components/schemas และ endpoint ที่เจอใต้ paths
4. อ่านผลลัพธ์ TypeScript ที่ generate แล้ว — interface หนึ่งตัวต่อ schema บวก request และ response types ของแต่ละ endpoint
5. copy ทั้งก้อนหรือเฉพาะ interface ที่ต้องการ แล้ววางลงโปรเจกต์ในชื่อไฟล์อย่าง src/types/api.generated.ts

เท่านี้คือจบ workflow ทั้งหมด เพราะไม่มี server round-trip คุณจึงปรับปรุงได้อิสระ: แก้ spec, paste ใหม่ แล้วดูว่า generated types ตอบสนองอย่างไร

จาก Schema สู่ Interface

หัวใจของเครื่องมือนี้คือการแมปจาก JSON Schema dialect ของ OpenAPI ไปสู่ระบบ type ของ TypeScript ซึ่งส่วนใหญ่ตรงไปตรงมาอย่างน่าใจหาย:

• type: string, type: integer และ type: number แมปไปเป็น string, number และ number ส่วน format อย่าง date-time หรือ uuid ยังคงเป็น string — TypeScript ไม่มี branded type ในตัวสำหรับค่าเหล่านี้โดย default
• nullable: true จะต่อ | null ท้าย property type ที่ generate ออกมา ทำให้ field ที่มีค่าแต่เป็น null ได้ถูก model อย่างตรงไปตรงมา แทนที่จะถูกมองข้ามเงียบ ๆ
• enum: [admin, editor, viewer] กลายเป็น string literal union: 'admin' | 'editor' | 'viewer' ค่าที่ผิดจะไม่ผ่านการ compile ตั้งแต่จุดเรียกใช้ แทนที่จะไปพังตอนตีสองใน production
• type: array ที่มี schema ใน items กลายเป็น ItemType[]
• allOf รวม subschema เป็น intersection type ซึ่งเป็นวาถีที่ OpenAPI แสดงการ composition และ field ฐานที่ใช้ร่วมกัน
• oneOf (และ anyOf) กลายเป็น union type โดยอาจ narrow เพิ่มเมื่อมี discriminator กำกับ
• additionalProperties: true ให้ index signature อย่าง { [key: string]: unknown } ส่วน additionalProperties: { type: string } ให้ record ที่มี type กำกับ

ด้าน input JSON กับ YAML ได้รับการปฏิบัติเท่ากันหมด JSON ถูก parse ด้วย JSON parser ตัวธรรมชาติ ส่วน YAML ผ่าน js-yaml parser ที่รันในเบราว์เซอร์ของคุณ เนื่องจากเอกสาร OpenAPI ให้ข้อมูลเหมือนกันในทั้งสองรูปแบบ การเลือกจึงกระทบแค่ความสะดวกเท่านั้น — anchor และ comment ของ YAML ดูแลรักษาง่ายกว่าสำหรับคน ขณะที่ JSON เป็นสิ่งที่ gateway และ code generator จำนวนมาก export ออกมา ไม่ว่าแบบไหนก็ paste มาตามที่เป็นเลย ไม่ต้องมีขั้นตอนแปลงล่วงหน้า

นี่คือตัวอย่าง schema เล็ก ๆ และสิ่งที่ converter ผลิตให้ จาก YAML นี้:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          nullable: true
        role:
          type: string
          enum: [admin, editor, viewer]
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true

TypeScript ที่ได้จะหน้าตาแบบนี้:

interface User {
  id: string;
  email: string | null;
  role: 'admin' | 'editor' | 'viewer';
  tags: string[];
  metadata: { [key: string]: unknown };
}

การเข้าใจสิ่งที่ generated types ไม่ ครอบคลุมก็สำคัญไม่แพ้กัน มันเป็น construct ระดับ compile-time: TypeScript types ถูก erase ตอน runtime ดังนั้นมันไม่ validate อะไรด้วยตัวเองเลย constraint อย่าง minLength, maximum, pattern และ format ไม่มี equivalent ใน TypeScript และจะหายไป — สำหรับ compiler แล้ว string ก็คือ string ไม่ว่า spec จะสัญญาเรื่องเนื้อหาไว้อย่างไร ถ้า payload ต้องข้าม trust boundary (ซึ่งเกิดขึ้นเสมอ) ให้จับ generated types จับคู่กับ runtime validator อย่าง Zod หรือ Valibot ที่ขอบของแอปพลิเคชัน pattern ที่นิยมคือ generate static types จาก spec แล้วเขียน runtime schemas คู่กันไป เพื่อให้ทั้งสองชั้นซิงก์กับ contract เดียวกัน

กรณีการใช้งานจริง

ความปลอดภัยของ type ฝั่ง frontend เมื่อเรียก REST API

use case ที่พบบ่อยที่สุด: แอป React, Vue หรือ Next.js ของคุณคุยกับ REST backend ที่เผยแพร่เอกสาร OpenAPI แปลง spec หนึ่งครั้งต่อการ release API, commit interface เหล่านั้น แล้ว type ทุก fetch wrapper, query hook และ store ด้วยมัน เมื่อ backend เปลี่ยนชื่อ field การ regenerate ครั้งถัดไปจะเปลี่ยนความคลาดเคลื่อนให้กลายเป็น compile error ใน component ของคุณ — โดนจับได้ตอน build ไม่ใช่โดนจับโดย user ตอน runtime

สร้างโครง SDK สำหรับ library ภายในองค์กร

ถ้าหลายทีมใช้ API เดียวกัน client library แบบบาง ๆ ที่มี type ครบช่วยประหยัดการประกาศรูปร่างเดิมซ้ำ ๆ ของทุกคน interface และ endpoint types ที่ generate แล้วให้ data layer ทั้งหมดของ SDK ภายในไม่กี่นาที คุณแค่เขียน transport logic (auth, retry, การจัดการ base URL) ครอบมัน การ regenerate หลัง release contract แต่ละครั้งทำให้ SDK ซื่อสัตย์โดยไม่ต้องขุดด้วยมือ

พัฒนาแบบ contract-first

ทีมที่ออกแบบเอกสาร OpenAPI ก่อนเขียนโค้ด server ได้ประโยชน์ทันที: แปลง draft spec แล้วส่ง interface ที่ได้ให้ทั้งฝั่ง backend และ frontend ใช้เป็นคลังคำศัพท์ร่วม types กลายเป็นชิ้นงานสำหรับ contract review — การถกเรื่อง role: 'admin' | 'editor' | 'viewer' ง่ายกว่าการถกย่อหน้าร้อยแก้วใน design doc อย่างมาก

รีวิวการเปลี่ยนแปลง API ผ่าน diff

เพราะ generated types เป็น deterministic การเปลี่ยน spec หนึ่งครั้งจึงให้ type diff ที่คาดเดาได้ commit ไฟล์ที่ generate ไว้แล้ว breaking change ทุกแบบ — property ถูกเปลี่ยนชื่อ, union ถูกขยาย, field ที่เพิ่งกลายเป็น nullable — จะโผล่ใน pull request diff พร้อมรัศมีผลกระทบที่ reviewer เห็นชัดเจน เมื่อรวมกับ Code Editor หรือ diff tool ระหว่างรีวิว มันเปลี่ยนคำถาม "API เปลี่ยนแล้วทำอะไรพังไหม" จากการเดา ให้เป็นการขวับตาดูรอบเดียว

Best Practices

• regenerate ทุกครั้งที่ spec เปลี่ยน types จะสดใหม่แค่ครั้ง generate ล่าสุดเท่านั้น ให้ถือว่าการ regenerate เป็นส่วนหนึ่งของกระบวนการ release API ไม่ใช่ migration ครั้งเดียวจบ
• commit generated types เข้า repo การเก็บผลลัพธ์ลง version control ให้ diff ที่รีวิวได้, editor support โดยไม่ต้องติดตั้งเพิ่ม และ build ที่ยังเดินได้แม้เพื่อนร่วมทีมยังไม่ได้ regenerate
• เติม runtime validation ที่ขอบระบบ static types บอกว่าอะไรควรมาถึง validator บังคับว่าอะไรมาถึงจริง วาง schema สไตล์ Zod ไว้ทุกจุดที่ข้อมูลไม่น่าเชื่อถือเข้าสู่ระบบ
• ตั้งชื่อ schema ให้มีความหมายใน spec ชื่อ interface มาตรงจาก key ของ schema components/schemas/UserProfile ให้ UserProfile ที่ใช้งานได้ ส่วน Schema12 ให้สิ่งที่ไม่มีใครอยาก import
• ให้ spec เป็น single source of truth ถ้าคุณแก้ generated interface ด้วยมือ แปลว่าคุณเพิ่งแตกสาขาจาก contract วิธีที่ถูกคือแก้ที่ spec, regenerate แล้วให้ compiler หา call site ที่กระทบ
• จำไว้ว่า types มีชีวิตเฉพาะตอน compile มัน document intent และจับความผิดพลาดตั้งแต่เนิ่น ๆ แต่ไม่เคยคุ้มกันโปรแกรมที่กำลังรันอยู่ วางงบให้ชั้น validation อย่างชัดเจน

เริ่มแปลง API Spec เป็น TypeScript Types วันนี้

เลิกดูแลสำเนา API ในหัวและใน editor ของคุณด้วยมือเถอะ paste spec เข้า OpenAPI to TypeScript Converter รับ interface ที่มันผลิตออกมา แล้วให้ compiler ช่วยคุมให้โค้ดฝั่ง client ซื่อสัตย์ต่อไปเรื่อย ๆ เครื่องมือรันในเบราว์เซอร์ทั้งหมด ไม่มีค่าใช้จ่าย และใช้เวลาประมาณเท่ากับการเขียน interface เดียวด้วยมือเสียอีก

เครื่องมือที่เกี่ยวข้อง

• JSON Formatter — จัดรูปและตรวจ JSON spec ให้เรียบร้อยก่อนนำไปแปลง
• JQ Playground — ลองสอบ response จริงจาก API เทียบกับรูปร่างที่ types สัญญาไว้
• TSConfig Generator — ตั้งค่า compiler แบบ strict ที่ทำให้ generated types คุ้มค่าที่สุด

ขอให้สนุกกับการสร้าง type!

คำถามที่พบบ่อย

ถ: converter อัปโหลด API spec ของฉันขึ้น server หรือเปล่า? ตอบ: ไม่ การ parse และ generate ทั้งหมดรันในเบราว์เซอร์ของคุณด้วย JavaScript แบบ local รวมถึง YAML parser ด้วย API contract ขององค์กรและ specification ของ partner จึงไม่มีทางออกจากเครื่อง

ถ: อ่านเอกสาร Swagger 2.0 ได้ไหม หรือได้แค่ OpenAPI 3.x? ตอบ: ได้ Swagger 2.0 เก็บ schema ไว้ใต้ definitions ส่วน OpenAPI 3.x เก็บไว้ใต้ components/schemas converter อ่านทั้งคู่แล้วผลิต interface ในสไตล์เดียวกัน

ถ: enum และ field ที่ nullable ถูกจัดการอย่างไร? ตอบ: enum จะกลายเป็น string literal union อย่าง 'admin' | 'editor' | 'viewer' และ nullable: true จะต่อ | null ท้าย property type ทำให้ทั้งสองอย่างถูก encode ในระบบ type แทนที่จะทิ้งไว้เป็น comment

ถ: generated types ตรวจสอบข้อมูลตอน runtime ให้ไหม? ตอบ: ไม่ TypeScript types ถูก erase ตอน runtime ดังนั้น constraint อย่าง pattern, minLength หรือ format ไม่ถูกบังคับใช้ ให้ใช้ library validation แบบ runtime ที่ขอบของระบบแทน

ถ: ควร paste รูปแบบไหน JSON หรือ YAML? ตอบ: แบบไหนก็ได้ เครื่องมือตรวจจับรูปแบบและ parse ทั้งคู่เหมือนกันหมด ใช้ตามที่ pipeline ของคุณปล่อยออกมาเลย ไม่ต้องเสียเวลาแปลงข้ามรูปแบบก่อน