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 gặp trục trặc ngay khi đặc tả của bạn chuyển vào Git. Không phải vì Git không phù hợp với các đặc tả, nó là nơi thích hợp cho chúng, mà vì các công cụ đánh giá của Git được xây dựng cho các kỹ sư đánh giá mã, chứ không phải cho QA, frontend, hay quản lý sản phẩm – những người cũng cần tham gia vào thiết kế API.

Nếu nhóm của bạn đã áp dụng phương pháp dựa trên tệp (lưu trữ đặc tả OpenAPI dưới dạng YAML hoặc JSON trong kho lưu trữ), bạn có thể đã gặp phải vấn đề này: đặc tả được phiên bản hóa và có thể xem xét, nhưng những người không phải kỹ sư vẫn xem trước Stoplight trong trình duyệt, đặt câu hỏi qua Slack DMs, và chờ các nhà phát triển cập nhật tệp trước khi họ có thể kiểm tra bất cứ điều gì. Bài đăng api-spec-as-code giải thích lý do tại sao Git là nguồn thông tin đáng tin cậy. Bài đăng này trình bày về khoảng cách cộng tác còn lại khi bạn đã đạt được điều đó, và cách các công cụ như Apidog thu hẹp khoảng cách đó mà không kéo đặc tả của bạn ra khỏi Git.

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

Git xử lý lịch sử thay đổi, phân nhánh (branching) và các bản diff của pull request. Đây là những tính năng cơ bản mạnh mẽ dành cho các kỹ sư. Tuy nhiên, chúng không giải quyết được một số nhu cầu cộng tác xuất hiện khi toàn bộ nhóm của bạn bắt đầu làm việc từ một đặc tả chung.

Bình luận trong giai đoạn thiết kế từ những người không phải kỹ sư. Một kỹ sư QA phát hiện ra một schema lỗi không nhất quán trong bản diff của PR không thể dễ dàng chú thích openapi.yaml dòng 247 bằng một câu hỏi có chuỗi. Giao diện PR của GitHub hoạt động tốt cho người đánh giá mã; nó ít tự nhiên hơn đối với các bên liên quan đọc đặc tả như tài liệu, chứ không phải mã nguồn.

Mock trực tiếp gắn liền với nhánh hiện tại. Các nhà phát triển frontend thường cần một máy chủ mock đang chạy trước khi quá trình triển khai backend hoàn tất. Với một tệp YAML thô trong Git, việc tạo mock đó yêu cầu một công cụ riêng biệt hoặc một bước thủ công. Tệp không tự động trở thành một artifact có thể chạy được.

Định tuyến thông báo theo vai trò. Khi một nhóm backend hợp nhất một thay đổi gây lỗi (breaking change) vào một đặc tả chung, các nhóm phía dưới (frontend, mobile, QA) cần biết. Git webhooks có thể thông báo đến một kênh Slack, nhưng chúng chỉ cung cấp tín hiệu chung chung “tệp đã thay đổi”. Các thông báo theo vai trò, chẳng hạn như “phản hồi của endpoint /payments đã thay đổi; đây là những đối tượng bị ảnh hưởng”, yêu cầu một lớp bổ sung.

Kiểm soát quyền truy cập đối với tài liệu. Một đặc tả trong kho lưu trữ GitHub công khai có thể đọc được bởi bất kỳ ai. Kho lưu trữ riêng tư giải quyết vấn đề đó, nhưng kiểm soát quyền truy cập ở cấp độ đối tượng, nơi một đối tác bên ngoài có thể đọc tài liệu endpoint nhưng không thể truy cập API quản trị nội bộ, không phải là thứ mà Git cung cấp nguyên bản.

Bốn khoảng cách này không phải là lý lẽ chống lại Git. Chúng là lý lẽ ủng hộ việc kết nối Git với một lớp cộng tác.

Lớp cộng tác làm gì (và không làm gì)

Khung làm việc hữu ích ở đây là: Git vẫn là nguồn thông tin đáng tin cậy; lớp cộng tác là thứ kết nối tệp đó với tài liệu, mock, đánh giá, thông báo và báo cáo CI/CD.

Các công cụ trong lĩnh vực này được chia thành khoảng hai loại:

Hiểu bảng này giúp tránh một sai lầm phổ biến: chọn một công cụ dựa trên một tính năng rồi sau đó phát hiện nó yếu ở một khía cạnh khác.

Xử lý Git của Bruno mạnh mẽ, và nó dừng lại ở lớp yêu cầu

Bruno xứng đáng có một mô tả trung thực trước khi bạn thiết kế quy trình làm việc xung quanh nó. Bruno Ultimate, đặc biệt, có lưu trữ bộ sưu tập gốc tệp, tích hợp Git mạnh mẽ, SSO, SCIM, hook quản lý bí mật và ghi nhật ký kiểm tra. Nếu nhu cầu chính của bạn là thực thi các yêu cầu chống lại một đặc tả mà bạn quản lý riêng, thì câu chuyện Git của Bruno thực sự vững chắc.

Bruno dừng lại ở lớp yêu cầu. Nó không tự động tạo tài liệu API từ một tệp OpenAPI đã cam kết, nó không tạo ra các máy chủ mock nhận biết nhánh từ tệp đó, và nó không định tuyến các thông báo cụ thể theo vai trò khi một đường dẫn đặc tả thay đổi. Những điều đó đòi hỏi một công cụ được lưu trữ riêng biệt hoặc một nền tảng kết nối lưu trữ gốc tệp với các tính năng cộng tác.

Chi phí tích hợp là có thật. Nếu bạn đang đánh giá Bruno cho một nhóm đã sử dụng Stoplight cho tài liệu và máy chủ mock, bạn không thay thế Stoplight; bạn đang thêm Bruno bên cạnh nó. Đó có thể là một quyết định đúng đắn, nhưng cần phải rõ ràng về kiến trúc.

Chế độ Spec-First của Apidog thu hẹp khoảng cách như thế nào

Chế độ Spec-First của Apidog (hiện đang trong giai đoạn thử nghiệm beta) được thiết kế chính xác cho kiến trúc này. Bạn cam kết một tệp openapi.yaml vào Git; Apidog đọc tệp đó làm nguồn có thẩm quyền và đặt các tính năng cộng tác lên trên mà không cần phân nhánh đặc tả vào cơ sở dữ liệu riêng của nó.

Đây là cách quy trình làm việc trông như thế nào trong thực tế.

Bước 1: Liên kết kho lưu trữ Git của bạn

Trong Apidog, bạn kết nối một dự án với kho lưu trữ GitHub, GitLab hoặc Bitbucket và trỏ nó đến đường dẫn tệp OpenAPI. Hướng dẫn đồng bộ hóa tích hợp Git của Apidog trình bày chi tiết các bước kết nối.

# openapi.yaml (committed in your repo at 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 (e.g., 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: Xem xét và bình luận từ đặc tả, không phải từ bản 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. Các thành viên trong nhóm có thể thêm bình luận trực tiếp vào các endpoint, schema và ví dụ phản hồi. Một kỹ sư QA xem xét đường dẫn POST /payments có thể gắn cờ header idempotency-key bị thiếu mà không cần chạm vào tệp YAML hoặc cần tài khoản GitHub có quyền truy cập cam kết.

Các bình luận được xâu chuỗi và giải quyết. Khi kỹ sư cập nhật openapi.yaml và đẩy một cam kết mới, dự án Apidog được liên kết sẽ phản ánh sự thay đổi. Cuộc hội thoại vẫn gắn liền với phần tử đặc tả, không phải số dòng.

Bước 3: Tự động tạo mock dành riêng cho nhánh

Với Chế độ Spec-First, mỗi nhánh của đặc tả của bạn có thể tạo ra một máy chủ mock riêng biệt. Một nhà phát triển frontend làm việc trên nhánh feature/payment-v2 sẽ nhận được một URL mock phản ánh schema mới trên nhánh đó. URL mock sản phẩm vẫn ổn định.

Điều này loại bỏ vấn đề “chờ backend” mà không cần ai đó chạy thủ công npx @stoplight/prism-cli mock openapi.yaml.

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

Khi một đường dẫn hoặc schema trong đặc tả thay đổi (khi hợp nhất), Apidog có thể gửi thông báo đến các kênh đã cấu hình. Bạn định tuyến các sự kiện thay đổi /payments đến một kênh Slack nơi các nhóm frontend và mobile đăng ký. Bạn định tuyến các sự kiện thay đổi /admin đến một kênh nội bộ riêng biệt.

Để thiết lập Slack và Teams, hãy xem webhook đến của Slack và webhook đến của Microsoft Teams để biết cấu hình webhook trên các nền tảng đó. Cài đặt thông báo của Apidog cho phép bạn liên kết các kênh này theo thẻ endpoint hoặc tiền tố đường dẫn.

Đáng để xác minh trong bản dùng thử: mức độ chi tiết của việc định tuyến thông báo (theo thẻ so với theo đường dẫn) và cách kiểm soát quyền truy cập đối với đối tượng tài liệu ánh xạ với cấu trúc vai trò của tổ chức bạn. Đây là những khả năng cần đánh giá dựa trên các yêu cầu cụ thể của bạn.

Kết nối lớp cộng tác với CI/CD

Lớp cộng tác hữu ích nhất khi nó kết nối với pipeline của bạn, chứ không chỉ các công cụ chat của nhóm. CLI của Apidog cho phép bạn chạy các bài kiểm tra hợp đồng đối với đặc tả đã cam kết như một bước CI. Kết hợp với một linter như Spectral hoặc Redocly CLI để xác thực đặc tả, bạn sẽ có một pipeline thực thi chất lượng đặc tả và làm nổi bật ngữ cảnh cộng tác cùng nhau.

Một bước GitHub Actions điển hình có thể trông như thế này:

# .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 (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

Đặc tả OpenAPI là tài liệu tham khảo chính tắc về những gì API của bạn cam kết. Chạy các bài kiểm tra hợp đồng đối với tệp đã cam kết có nghĩa là pipeline CI của bạn sẽ thất bại nếu dịch vụ đang chạy khác biệt so với đặc tả, chứ không chỉ khi các bài kiểm tra đơn vị (unit tests) vượt qua.

Để tìm hiểu sâu hơn về mẫu quy trình làm việc gốc Git mà điều này phù hợp, quy trình làm việc API gốc Git sẽ hướng dẫn cách xây dựng pipeline đó từ đầu đến cuối.

So sánh các lựa chọn chính cho các nhóm làm việc dựa trên tệp

Nếu bạn đang đánh giá các công cụ sau khi đọc bài này, đây là một so sánh trực tiếp trên các khía cạnh quan trọng đối với cộng tác dựa trên tệp. Các khả năng được đánh dấu bằng dấu hỏi đáng để xác minh trong bản dùng thử của riêng bạn; chúng thay đổi tùy theo cấp gói và cấu hình.

Để so sánh rộng hơn bao gồm SwaggerHub, hãy xem swaggerhub-vs-apidog-collaboration.

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

Chúng tôi có thể tiếp tục sử dụng đánh giá PR của Git cùng với bình luận của Apidog không?

Có. Hai luồng phục vụ các đối tượng khác nhau. Đánh giá PR của Git dành cho các kỹ sư xem xét thay đổi YAML; bình luận của Apidog dành cho các bên liên quan về sản phẩm, QA và frontend xem xét đặc tả dưới dạng tài liệu. Cả hai có thể chạy song song mà không xung đột. Tệp đã cam kết vẫn là nguồn thông tin đáng tin cậy duy nhất cho cả hai.

Điều gì sẽ xảy ra nếu ai đó chỉnh sửa đặc tả trong Apidog thay vì tệp?

Trong Chế độ Spec-First, các chỉnh sửa được thực hiện thông qua giao diện Apidog có thể được đẩy ngược lại Git dưới dạng các cam kết. Quy trình là: chỉnh sửa trong UI, cam kết vào nhánh, xem xét PR trong Git, hợp nhất. Điều này đáng để xác nhận trong bản dùng thử của bạn vì hướng đồng bộ hóa chính xác (Apidog sang Git so với Git sang Apidog) ảnh hưởng đến cách nhóm của bạn quyết định nơi các chỉnh sửa bắt nguồn. Để xem hướng dẫn từng bước về chính Chế độ Spec-First, hãy xem hướng dẫn chi tiết chế độ Spec-First của Apidog (beta).

Chế độ Spec-First có hoạt động với các monorepo có nhiều tệp OpenAPI không?

Nhiều tệp đặc tả cho mỗi dự án là một mẫu monorepo phổ biến. Apidog hỗ trợ nhiều dự án, mỗi dự án được liên kết với một đường dẫn tệp khác nhau. Việc một dự án Apidog duy nhất có thể ánh xạ tới nhiều tệp đặc tả hay liệu các quy tắc lint tùy chỉnh có thể được chia sẻ giữa các dự án đó hay không, đáng để thử nghiệm trong bản dùng thử với bố cục kho lưu trữ cụ thể của bạn.

Điều này so sánh với Redocly như thế nào đối với các nhóm làm việc dựa trên tệp?

Redocly CLI mạnh mẽ trong việc lint đặc tả, đóng gói và tạo tài liệu từ các tệp. Nền tảng được lưu trữ của Redocly bổ sung các tính năng đánh giá và nhóm. Sự khác biệt tương tự như so sánh với Stoplight: lớp cộng tác của Redocly có sẵn trên các gói trả phí. Điểm khác biệt của Apidog là sự kết hợp toàn diện các tính năng mock, kiểm thử hợp đồng, thông báo và tài liệu trên một nền tảng đọc từ tệp đã cam kết của bạn.

Còn về bộ công cụ riêng của Sáng kiến OpenAPI thì sao?

Sáng kiến OpenAPI tự xuất bản đặc tả; nó không xuất bản một nền tảng cộng tác. Hệ sinh thái các công cụ triển khai đặc tả là những gì bạn đang lựa chọn. Bất kỳ công cụ nào trong bài đăng này tuyên bố “hỗ trợ OpenAPI” nên được kiểm tra với OpenAPI 3.1 nếu đó là phiên bản đặc tả của bạn, vì mức độ hỗ trợ 3.1 khác nhau.

Kết luận

Nếu nhóm của bạn đã lưu trữ đặc tả OpenAPI trong Git, vấn đề quản lý tệp đã được giải quyết. Vấn đề cộng tác thì chưa. Bình luận trong giai đoạn thiết kế từ những người không phải kỹ sư, mock dành riêng cho nhánh cho frontend, thông báo nhắm mục tiêu theo vai trò về các thay đổi gây lỗi, và tài liệu được kiểm soát truy cập đều yêu cầu một lớp kết nối tệp đã cam kết của bạn với phần còn lại của quy trình làm việc của nhóm.

Lớp đó không nhất thiết phải thay thế Git. Nó nên đọc từ Git, xây dựng dựa trên Git và không cản trở khi các kỹ sư đang thực hiện đánh giá mã trong các PR.

Nếu thiết lập hiện tại của bạn có Stoplight hoặc một tài liệu chung xử lý cộng tác trong khi Git xử lý việc quản lý phiên bản, thì đó chính xác là kiến trúc mà Chế độ Spec-First của Apidog được thiết kế để hợp nhất. Vì nó vẫn đang trong giai đoạn beta, hãy chạy thử nghiệm tập trung vào các khả năng mà nhóm bạn cần nhất (kiểm soát truy cập tài liệu, tái sử dụng schema giữa các dự án, mức độ chi tiết thông báo) trước khi cam kết. Tải Apidog và kết nối nó với một nhánh của kho lưu trữ đặc tả hiện có của bạn để xem lớp cộng tác phù hợp như thế nào với quy trình làm việc mà nhóm bạn đã có.