Cộng tác OpenAPI không từ bỏ Git: Cách đội ngũ làm việc trên tệp phối hợp

Sự cộng tác của nhóm OpenAPI thường bắt đầu gặp vấn đề khi đặc tả được đưa vào Git. Git vẫn là nơi phù hợp để version hóa openapi.yaml hoặc openapi.json, nhưng giao diện review của Git được tối ưu cho kỹ sư đọc diff mã nguồn, không phải cho QA, frontend hay product manager cùng tham gia thiết kế API.

Dùng thử Apidog ngay hôm nay

Nếu nhóm của bạn đã áp dụng mô hình file-first, bạn có thể đã thấy luồng này: đặc tả được commit và review qua PR, nhưng người không viết backend vẫn phải xem preview trong trình duyệt, hỏi qua Slack DM, rồi chờ developer cập nhật file trước khi kiểm thử. Bài viết api-spec-as-code giải thích vì sao Git nên là nguồn thông tin đáng tin cậy. Bài này tập trung vào phần còn thiếu: cách thêm lớp cộng tác, mock, thông báo và CI/CD phía trên Git bằng các công cụ như Apidog mà không kéo đặc tả ra khỏi repository.

Khoảng cách mà chỉ Git không thể lấp đầy

Git xử lý tốt lịch sử thay đổi, branch, merge request/pull request và diff. Tuy nhiên, khi toàn bộ nhóm làm việc từ một đặc tả OpenAPI chung, bạn thường cần thêm các khả năng sau.

1. Bình luận thiết kế cho người không viết mã

QA hoặc product manager có thể phát hiện response schema không nhất quán, nhưng việc comment trực tiếp vào dòng 247 của openapi.yaml trong GitHub PR không phải lúc nào cũng tự nhiên.

Với API spec, nhiều người muốn review theo ngữ cảnh:

• endpoint nào thay đổi
• request body có field nào mới
• response error có nhất quán không
• example có đủ để frontend triển khai không

Diff YAML chỉ phù hợp với người quen đọc mã.

2. Mock server theo branch

Frontend thường cần mock API trước khi backend hoàn tất. Nếu chỉ có file YAML trong Git, nhóm phải tự chạy công cụ như:

npx @stoplight/prism-cli mock api/openapi.yaml

Cách này hoạt động, nhưng cần thao tác thủ công và khó tách mock theo branch như feature/payment-v2, develop, hoặc main.

3. Thông báo theo vai trò và phạm vi thay đổi

Git webhook có thể báo “file đã thay đổi”, nhưng thường chưa đủ chi tiết.

Ví dụ hữu ích hơn là:

Response của POST /payments đã thay đổi. Frontend, mobile và QA cần kiểm tra lại flow thanh toán.

Để làm được việc này, bạn cần lớp hiểu được cấu trúc OpenAPI, không chỉ biết rằng openapi.yaml có diff.

4. Quyền truy cập tài liệu API

Repo private giải quyết quyền truy cập ở cấp repository. Nhưng trong thực tế, bạn có thể cần:

• partner chỉ xem nhóm endpoint public
• QA xem đầy đủ tài liệu test
• backend xem endpoint nội bộ
• nhóm external không xem API admin

Git không cung cấp quyền truy cập chi tiết theo endpoint hoặc nhóm tài liệu.

Lớp cộng tác nên làm gì

Mô hình thực tế nên là:

Git là source of truth. Lớp cộng tác đọc từ Git và tạo tài liệu, mock, bình luận, thông báo, kiểm thử và báo cáo CI/CD phía trên file đã commit.

So sánh nhanh các nhóm công cụ:

Danh mục	Ví dụ	Điểm mạnh	Điểm cần lưu ý
Nền tảng đặc tả được lưu trữ	Stoplight, SwaggerHub	UI tốt, bình luận, kiểm soát truy cập	Thường duy trì bản sao đặc tả riêng; Git có thể chỉ là tích hợp phụ
Lớp cộng tác dựa trên file gốc	Apidog Spec-First mode, Redocly	Làm việc từ file đã commit; Git vẫn có thẩm quyền	Thêm tài liệu, mock, comment và CI phía trên Git
API client gốc Git	Bruno, Insomnia	Quản lý collection dạng file tốt	Tập trung vào request/client; tài liệu, mock và báo cáo cần lớp khác

Điểm quan trọng: đừng chọn công cụ chỉ vì một tính năng. Hãy kiểm tra toàn bộ workflow: Git sync, review, mock, quyền truy cập, thông báo và CI/CD.

Bruno mạnh ở lớp request, nhưng không thay thế lớp cộng tác API spec

Bruno có cách tiếp cận file-native tốt. Bruno Ultimate hỗ trợ lưu collection dạng file, tích hợp Git, SSO, SCIM, secret management hooks và audit logging. Nếu nhu cầu chính của bạn là quản lý và chạy request collection trong Git, Bruno là một lựa chọn mạnh.

Nhưng Bruno dừng chủ yếu ở lớp request. Nó không tự động biến openapi.yaml đã commit thành:

• tài liệu API tương tác
• mock server theo branch
• bình luận theo endpoint/schema
• thông báo theo đường dẫn hoặc tag
• báo cáo hợp đồng gắn với CI/CD

Vì vậy, nếu nhóm của bạn đang dùng Stoplight để tạo docs và mock, việc thêm Bruno không tự động thay thế Stoplight. Bạn đang thêm một API client bên cạnh lớp tài liệu/cộng tác hiện có.

Cách Apidog Spec-First thu hẹp khoảng cách

Chế độ Spec-First của Apidog hiện đang trong giai đoạn beta. Ý tưởng chính:

1. Bạn commit openapi.yaml vào Git.
2. Apidog đọc file đó như nguồn có thẩm quyền.
3. Apidog tạo lớp cộng tác phía trên: tài liệu, bình luận, mock, thông báo và kiểm thử.

Bước 1: Liên kết repository Git

Trong Apidog, liên kết project với GitHub, GitLab hoặc Bitbucket, sau đó trỏ đến file OpenAPI trong repo. Hướng dẫn đồng bộ hóa tích hợp Git của Apidog mô tả chi tiết bước kết nối.

Ví dụ repo có cấu trúc:

.
├── api
│   └── openapi.yaml
├── src
└── .github
    └── workflows

File đặc tả:

# api/openapi.yaml
openapi: "3.1.0"
info:
  title: Payments API
  version: "2.4.0"

paths:
  /payments:
    post:
      summary: Create a payment
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: Payment created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "422":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, source]
      properties:
        amount:
          type: integer
          description: Amount in smallest currency unit, for example cents
        currency:
          type: string
          enum: [usd, eur, gbp]
        source:
          type: string
          description: Payment method token

    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, completed, failed]

    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

Bước 2: Review đặc tả như tài liệu, không chỉ như diff

Sau khi liên kết, Apidog hiển thị đặc tả dưới dạng tài liệu tương tác. Thành viên nhóm có thể comment trực tiếp vào endpoint, schema hoặc response example.

Ví dụ QA review POST /payments và phát hiện thiếu header Idempotency-Key. Thay vì comment vào YAML diff, QA có thể đặt câu hỏi ngay tại endpoint liên quan.

Workflow nên dùng:

1. Developer tạo branch và cập nhật api/openapi.yaml.
2. Apidog sync branch/spec.
3. QA, frontend hoặc PM comment trên tài liệu.
4. Developer sửa spec.
5. PR được review và merge trong Git.

Điểm quan trọng: comment gắn với phần tử API, không chỉ số dòng trong file.

Bước 3: Tạo mock theo branch

Với Spec-First mode, mỗi branch có thể có mock server riêng. Điều này hữu ích khi frontend cần build trước backend.

Ví dụ:

Branch	Mục đích	Mock
main	API ổn định	mock cho tài liệu hiện tại
develop	API sắp release	mock cho staging
feature/payment-v2	thay đổi payment flow	mock riêng cho frontend test

Kết quả: frontend có thể gọi mock phản ánh schema mới trên branch, trong khi mock production/stable vẫn không đổi.

Bước 4: Định tuyến thông báo đến đúng nhóm

Khi merge một thay đổi trong spec, Apidog có thể gửi thông báo đến các kênh đã cấu hình.

Ví dụ cấu hình mong muốn:

Phạm vi thay đổi	Kênh nhận thông báo
/payments/**	Slack #frontend-payments, #mobile-payments, #qa-payments
/admin/**	Slack #backend-internal
tag public-api	Teams channel của nhóm partner integration

Để thiết lập webhook, tham khảo:

• webhook đến của Slack
• webhook đến của Microsoft Teams

Khi dùng thử, nên kiểm tra kỹ mức độ chi tiết mà nhóm bạn cần: định tuyến theo tag, theo path prefix, theo project hay theo vai trò.

Kết nối với CI/CD

Lớp cộng tác hữu ích nhất khi nó nằm trong pipeline, không chỉ trong UI. Bạn có thể kết hợp:

• Spectral hoặc Redocly CLI để lint OpenAPI
• Apidog CLI để chạy contract test
• GitHub Actions/GitLab CI để chặn PR hoặc merge nếu spec/API không hợp lệ

Ví dụ GitHub Actions:

# .github/workflows/api-spec.yml
name: API spec validation and test

on: [push, pull_request]

jobs:
  validate-and-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec with Spectral
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint api/openapi.yaml --ruleset .spectral.yaml

      - name: Run Apidog contract tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          npx apidog-cli run \
            --project-id ${{ vars.APIDOG_PROJECT_ID }} \
            --test-suite "Payments API smoke" \
            --environment staging

Một ruleset Spectral tối thiểu có thể bắt buộc mỗi operation phải có operationId:

# .spectral.yaml
extends: ["spectral:oas"]

rules:
  operation-operationId:
    description: Every operation must have an operationId
    severity: error
    given: $.paths[*][*]
    then:
      field: operationId
      function: truthy

Đặc tả OpenAPI là tài liệu tham chiếu chính tắc về những gì API cam kết. Khi contract test chạy trong CI, pipeline có thể fail nếu service thực tế không khớp với spec, ngay cả khi unit test vẫn pass.

Để xem workflow gốc Git đầy đủ hơn, tham khảo quy trình làm việc API gốc Git.

Checklist đánh giá công cụ cho nhóm file-first

Nếu nhóm đang chọn công cụ, hãy kiểm tra theo checklist sau:

• Git có tiếp tục là source of truth không?
• Công cụ có đọc trực tiếp openapi.yaml hoặc openapi.json đã commit không?
• Comment có gắn với endpoint/schema không?
• Có mock server theo branch không?
• Có thể giới hạn quyền xem tài liệu theo vai trò không?
• Có thông báo theo path/tag không?
• Có CLI hoặc API để chạy trong CI/CD không?
• Có hỗ trợ OpenAPI 3.1 nếu spec của bạn đang dùng 3.1 không?
• Có tránh tạo bản sao spec gây lệch giữa Git và UI không?

So sánh nhanh:

Khả năng	Stoplight	SwaggerHub	Apidog Spec-First beta
Git làm nguồn có thẩm quyền	Tùy chọn, thường có bản sao riêng	Tùy chọn	Có, trong Spec-First mode
Bình luận trong giai đoạn thiết kế	Có	Có	Có
Mock theo branch	Có	Một phần	Có
Truy cập tài liệu theo vai trò	Có	Có	Nên kiểm tra trong bản dùng thử
Tái sử dụng schema giữa các project	Có	Có	Nên kiểm tra trong bản dùng thử
Contract test trong CI/CD	Qua Prism	Hạn chế	Có, qua Apidog CLI
Custom lint rules	Qua Spectral	Hạn chế	Nên kiểm tra trong bản dùng thử
SSO/SCIM	Gói trả phí	Enterprise	Nên kiểm tra trong bản dùng thử
Định tuyến thông báo	Qua webhooks	Hạn chế	Có
File-native, tránh trùng lặp spec	Không	Không	Có, trong Spec-First mode

Để so sánh rộng hơn với SwaggerHub, xem swaggerhub-vs-apidog-collaboration.

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

Có nên tiếp tục review PR trong Git không?

Có. Nên giữ cả hai luồng:

• Git PR review: dành cho kỹ sư kiểm tra diff YAML, naming, schema, backward compatibility.
• Apidog comment: dành cho QA, frontend, product và stakeholder review API như tài liệu.

File đã commit vẫn là nguồn thông tin đáng tin cậy cho cả hai.

Nếu ai đó chỉnh sửa spec trong Apidog thì sao?

Trong Spec-First mode, chỉnh sửa qua UI có thể được đẩy ngược về Git dưới dạng commit. Workflow nên là:

1. Chỉnh sửa trong UI.
2. Commit vào branch.
3. Review PR trong Git.
4. Merge.
5. Apidog sync lại trạng thái mới.

Bạn nên xác nhận hướng sync chính xác trong bản dùng thử vì điều này ảnh hưởng đến quy tắc nội bộ: chỉnh sửa bắt nguồn từ Git, từ UI, hay cả hai. Xem thêm hướng dẫn chi tiết chế độ Spec-First của Apidog beta.

Spec-First mode có phù hợp với monorepo không?

Có thể phù hợp nếu mỗi project Apidog trỏ tới một file spec khác nhau trong monorepo.

Ví dụ:

.
├── services
│   ├── payments
│   │   └── openapi.yaml
│   ├── billing
│   │   └── openapi.yaml
│   └── identity
│       └── openapi.yaml

Điểm nên thử nghiệm:

• một project Apidog có thể ánh xạ nhiều file spec không
• schema dùng chung giữa nhiều service được xử lý thế nào
• ruleset lint có thể chia sẻ giữa các project không

So với Redocly thì sao?

Redocly CLI mạnh ở lint, bundle và tạo tài liệu từ file OpenAPI. Nền tảng hosted của Redocly bổ sung review và collaboration.

Khác biệt cần đánh giá là mức độ tích hợp end-to-end: mock, contract test, notification, tài liệu và Git sync trong cùng một workflow. Với Apidog, điểm nhấn là kết hợp các khả năng này trên một nền tảng đọc từ file đã commit.

Còn công cụ chính thức của OpenAPI Initiative?

OpenAPI Initiative xuất bản đặc tả, không cung cấp nền tảng cộng tác. Bạn vẫn cần chọn công cụ trong hệ sinh thái.

Nếu spec của bạn dùng OpenAPI 3.1, hãy kiểm tra từng công cụ với OpenAPI 3.1, vì mức độ hỗ trợ có thể khác nhau.

Kết luận

Nếu nhóm của bạn đã lưu đặc tả OpenAPI trong Git, phần versioning đã được giải quyết. Phần còn lại là cộng tác: review dễ đọc cho người không viết mã, mock theo branch cho frontend, thông báo đúng nhóm khi API thay đổi, quyền truy cập tài liệu và contract test trong CI/CD.

Lớp cộng tác tốt không nên thay thế Git. Nó nên đọc từ Git, bổ sung workflow phía trên Git và để kỹ sư tiếp tục review PR như bình thường.

Nếu hiện tại bạn đang dùng Git để quản lý version và một công cụ khác để làm tài liệu/mock, đó là đúng loại kiến trúc mà Chế độ Spec-First của Apidog hướng đến. Vì tính năng vẫn ở beta, hãy thử với một branch hoặc một service nhỏ trước. Tập trung kiểm tra các điểm quan trọng với nhóm bạn: quyền truy cập tài liệu, tái sử dụng schema, mock theo branch, thông báo theo path/tag và CI contract test. Sau đó tải Apidog và kết nối với repository spec hiện có để đánh giá workflow thực tế.