Apidog Chế Độ Spec-First Là Gì

Apidog Spec-First Mode là không gian làm việc beta cho các nhóm xem tài liệu đặc tả OpenAPI như mã nguồn. Thay vì chỉnh API qua form, bạn chỉnh trực tiếp openapi.yaml hoặc openapi.json trong trình chỉnh sửa kiểu IDE, xác thực đặc tả, commit và đồng bộ hai chiều với Git. Nếu workflow hiện tại của bạn là sửa spec, review qua pull request rồi merge vào GitHub/GitLab/Azure DevOps, đây là chế độ nên thử.

Thử Apidog ngay hôm nay

Bài viết này hướng dẫn cách dùng Spec-First Mode theo hướng triển khai thực tế: khi nào nên dùng, cách thiết lập, cách chỉnh sửa spec, commit, push và những giới hạn cần lưu ý trong giai đoạn beta. Nếu bạn muốn hiểu thêm nền tảng của cách tiếp cận này, hãy đọc thêm về quy trình làm việc API gốc Git.

Chế độ Apidog Spec-First là gì?

Chế độ Spec-First là một chế độ chỉnh sửa beta trong Apidog, nơi thiết kế API tồn tại dưới dạng tài liệu OpenAPI thô. Bạn mở file, chỉnh YAML hoặc JSON, xác thực, commit và đẩy thay đổi lên Git. Apidog giữ spec và repository đồng bộ hai chiều: kéo thay đổi từ đồng đội về editor, hoặc đẩy chỉnh sửa của bạn ngược lại repo.

Cách làm này phù hợp với các nhóm đã vận hành theo Git-native workflow: backend engineers, platform teams, API-first teams hoặc bất kỳ nhóm nào review hợp đồng API qua pull request. File spec trở thành nguồn đáng tin cậy duy nhất, còn Git xử lý lịch sử, review, branch và merge như với phần còn lại của codebase.

Điểm khác biệt chính: nhiều công cụ API ẩn OpenAPI spec sau giao diện form. Spec-First Mode đưa bạn làm việc trực tiếp với file.

Spec-First Mode và Design-First Mode khác nhau thế nào?

Apidog có hai chế độ chính:

• Design-First Mode: chỉnh API bằng form và UI trực quan.
• Spec-First Mode: chỉnh trực tiếp YAML/JSON như code.

Nếu cần phân tích sâu hơn về trade-off, xem bài so sánh spec-first và design-first.

Khía cạnh	Design-First Mode	Spec-First Mode Beta
Trình chỉnh sửa chính	Form trực quan và bảng UI	Trình chỉnh sửa mã YAML/JSON
Nguồn đáng tin cậy	Cơ sở dữ liệu dự án Apidog	File spec trong Git repository
Đồng bộ Git	Dựa trên import/export	Đồng bộ hai chiều tự nhiên
Phù hợp nhất cho	Nhóm hỗn hợp, người thích UI	Nhóm kỹ thuật ưu tiên Git
Độ khó học	Dễ tiếp cận, có hướng dẫn	Dễ nếu bạn đã biết OpenAPI

Không có chế độ nào “tốt hơn” tuyệt đối. Chọn chế độ theo workflow thật của nhóm. Nếu nhóm bạn review spec như code, Spec-First Mode sẽ tự nhiên hơn.

Các tính năng chính

Spec-First Mode không chỉ là một ô nhập YAML. Nó gồm editor, outline, Git sync, trạng thái đồng bộ và kiểm soát thay đổi.

Trình chỉnh sửa OpenAPI kiểu IDE

Trung tâm của workspace là trình chỉnh sửa mã cho tài liệu OpenAPI. Bạn chỉnh trực tiếp YAML hoặc JSON thô.

Editor hỗ trợ:

• Tô sáng cú pháp cho YAML/JSON.
• Xác thực schema theo OpenAPI.
• Tự động hoàn thành cho OpenAPI và Swagger.
• Gợi ý keyword, field name và cấu trúc hợp lệ.
• Phát hiện lỗi như thiếu field bắt buộc, sai $ref, hoặc response object không hợp lệ.

Ví dụ một đoạn OpenAPI bạn có thể chỉnh trực tiếp:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Khi làm việc sâu trong schema, autocomplete giúp tránh nhầm các keyword như additionalProperties, items, required, format hoặc $ref.

Dàn ý điều hướng tự động

Một file openapi.yaml thực tế có thể dài hàng nghìn dòng. Spec-First Mode phân tích file và tạo outline ở thanh bên trái.

Outline giúp bạn nhảy nhanh đến:

• paths
• endpoint cụ thể như POST /orders
• operation
• schema
• component
• response hoặc request body

Thay vì tìm “dòng 1847”, bạn điều hướng theo ý nghĩa của API. Khi spec thay đổi, outline cập nhật theo nội dung thực tế trong file.

Đồng bộ Git hai chiều

Đồng bộ Git là phần cốt lõi của Spec-First Mode.

Bạn kết nối Apidog với repository chứa OpenAPI spec. Sau đó:

• Pull để đưa thay đổi từ repo vào editor.
• Edit YAML/JSON trong Apidog.
• Commit thay đổi với message rõ ràng.
• Push trở lại repository.

Các provider được hỗ trợ:

Nhà cung cấp	Cách kết nối
GitHub	Tích hợp trực tiếp
GitLab	Tích hợp trực tiếp
Azure DevOps	Thông qua Generic Git Connection

Nếu bạn muốn xem hướng dẫn theo từng bước với GitHub, đọc bài đồng bộ tài liệu đặc tả OpenAPI với GitHub.

Commit, push và trạng thái đồng bộ

Spec-First Mode dùng mô hình Git quen thuộc. Sau khi chỉnh sửa, bạn:

1. Xem lại thay đổi.
2. Viết commit message.
3. Commit.
4. Push lên branch đã kết nối.

Chỉ báo đồng bộ cho biết trạng thái hiện tại, ví dụ khi spec local đã khớp với repository. Nhờ đó, bạn biết phiên bản trước mặt mình đã được đẩy lên Git hay vẫn còn thay đổi cục bộ.

Một commit message nên cụ thể, ví dụ:

Add POST /invoices endpoint

hoặc:

Update user response schema

Theo dõi thay đổi file

Trước khi commit, Spec-First Mode hiển thị các thay đổi ở cấp file. Mỗi thay đổi có thể được đánh dấu là:

• đã sửa đổi
• đã thêm
• đã xóa

Đây là bước kiểm tra quan trọng trước khi đưa spec vào lịch sử chung. Nếu một thử nghiệm không còn cần thiết, bạn có thể loại bỏ chỉnh sửa chưa push để giữ lịch sử Git sạch hơn.

Dự án gắn với repository, branch và quyền nhóm

Một dự án Spec-First được tạo từ:

• một Git repository cụ thể
• một branch cụ thể, thường là main
• quyền truy cập của nhóm

Điều này giúp dự án luôn trỏ đến một vị trí thật trong Git. Quyền của nhóm cũng được cấu hình trong quá trình thiết lập, để bạn kiểm soát ai có thể truy cập và chỉnh sửa hợp đồng API.

Cách thiết lập Spec-First Mode

Quy trình thiết lập ngắn gọn như sau. Tài liệu chính thức có tại docs.apidog.com/spec-first-mode-beta-2058268m0.

1. Mở module APIs trong Apidog.
2. Chuyển chế độ. Ở góc dưới bên trái, chuyển từ Design-First Mode sang Spec-First Mode.
3. Kết nối Git provider.
   • GitHub: dùng tích hợp trực tiếp.
   • GitLab: dùng tích hợp trực tiếp.
   • Azure DevOps: dùng Generic Git Connection.
4. Tạo project từ repository. Chọn repo chứa openapi.yaml hoặc openapi.json.
5. Chọn branch. Thường là main, hoặc branch mà nhóm bạn dùng để quản lý spec.
6. Cấu hình quyền nhóm. Đặt ai có thể truy cập và chỉnh sửa project.
7. Mở file spec. Chỉnh YAML/JSON trong editor.
8. Dùng outline để điều hướng.
9. Review thay đổi. Kiểm tra file đã thêm/sửa/xóa.
10. Commit. Viết commit message rõ ràng.
11. Push lên repository.
12. Kiểm tra trạng thái đồng bộ. Đảm bảo spec local và repo đã khớp.

Tóm lại: chuyển chế độ, kết nối Git, chọn repo/branch, chỉnh spec, commit, push, xác minh.

Quy trình làm việc hằng ngày

Sau khi thiết lập, workflow thường diễn ra như sau:

1. Pull phiên bản mới nhất từ branch đã kết nối.
2. Mở outline để đến endpoint hoặc schema cần chỉnh.
3. Chỉnh YAML/JSON trực tiếp.
4. Dùng autocomplete và validation để giảm lỗi OpenAPI.
5. Xem lại thay đổi file.
6. Commit với message rõ ràng.
7. Push lên Git.
8. Để đồng đội review qua pull request nếu workflow của nhóm yêu cầu.

Ví dụ bạn thêm schema Invoice:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

Với cách này, spec được xử lý như code: có versioning, có review, có commit history và có branch.

Ai nên dùng Spec-First Mode?

Spec-First Mode phù hợp nếu nhóm bạn:

• đã quen với Git
• review API contract qua pull request
• muốn đặt OpenAPI spec cạnh service code
• thích chỉnh YAML/JSON trực tiếp
• có backend hoặc platform engineers chịu trách nhiệm chính cho API contract
• muốn xem spec là nguồn đáng tin cậy duy nhất

Nên chọn Design-First Mode nếu nhóm bạn:

• muốn UI trực quan hơn
• có nhiều người không phải kỹ sư cùng tham gia thiết kế API
• thích điền form hơn chỉnh YAML
• cần một trải nghiệm có hướng dẫn nhiều hơn

Nếu vẫn phân vân, xem thêm bài so sánh Spec-First và Design-First.

Hạn chế và lưu ý trong giai đoạn beta

Spec-First Mode hiện là tính năng beta, vì vậy cần đặt kỳ vọng đúng.

Một số điểm cần lưu ý:

• Hành vi và khả năng có thể thay đổi khi Apidog tiếp tục hoàn thiện tính năng.
• GitHub và GitLab có tích hợp trực tiếp.
• Azure DevOps dùng Generic Git Connection.
• Nếu nhóm phụ thuộc vào một Git provider hoặc workflow đặc thù, hãy kiểm tra trước khi áp dụng cho project quan trọng.
• Vì spec đồng bộ với repository thật, bạn vẫn cần tuân thủ kỷ luật Git: commit cẩn thận, review thay đổi trước khi push và loại bỏ chỉnh sửa không cần thiết.

Cách an toàn nhất là thử trước trên repository không quan trọng, chạy một vòng edit → commit → push, rồi mới mở rộng sang workflow chính.

Câu hỏi thường gặp

Spec-First Mode có miễn phí không?

Spec-First Mode là tính năng beta trong Apidog. Quyền truy cập phụ thuộc vào gói Apidog và trạng thái beta của tài khoản. Cách kiểm tra nhanh nhất là mở module APIs và thử bật Spec-First Mode.

Git provider nào được hỗ trợ?

GitHub và GitLab được hỗ trợ qua tích hợp trực tiếp. Azure DevOps hoạt động qua Generic Git Connection bằng thông tin đăng nhập Git tiêu chuẩn. Các Git server khác cũng có thể hoạt động qua kết nối chung nếu tương thích với Git tiêu chuẩn.

Có thể chuyển lại Design-First Mode không?

Có. Bạn có thể dùng nút chuyển chế độ ở góc dưới bên trái module APIs để chuyển giữa Spec-First Mode và Design-First Mode. Bạn không bị khóa vào một chế độ duy nhất.

Có thể chỉnh định dạng file nào?

Bạn có thể chỉnh tài liệu OpenAPI ở dạng YAML hoặc JSON thô. Editor hỗ trợ tô sáng cú pháp, xác thực schema và autocomplete cho OpenAPI/Swagger.

Điều gì xảy ra với chỉnh sửa chưa push?

Chỉnh sửa chưa push vẫn ở local cho đến khi bạn đẩy lên repository. Spec-First Mode theo dõi thay đổi dưới dạng đã sửa, đã thêm hoặc đã xóa. Nếu không muốn giữ thay đổi, bạn có thể loại bỏ trước khi push để nó không đi vào lịch sử chung.

Kết luận

Apidog Spec-First Mode đưa OpenAPI editor và Git workflow vào cùng một nơi. Bạn chỉnh spec dưới dạng YAML/JSON, điều hướng bằng outline, xác thực khi viết, commit thay đổi và đồng bộ hai chiều với GitHub, GitLab hoặc Azure DevOps.

Đây là tính năng beta dành cho các nhóm ưu tiên Git và muốn xem OpenAPI spec như mã nguồn. Nếu nhóm bạn đang quản lý API contract bằng pull request, hãy bật Spec-First Mode trong module APIs, kết nối một repository và thử một chu trình nhỏ: chỉnh sửa, commit, push, rồi xác minh đồng bộ. Khi sẵn sàng, bạn có thể thử Spec-First Mode trong tài liệu.