Trải Nghiệm Spec-First Mode Của Apidog: Thiết Kế API Không Còn Dành Riêng Cho Designer

Có hai cách phổ biến để quản lý đặc tả API: viết OpenAPI trực tiếp trong Git, hoặc thiết kế API bằng giao diện trực quan rồi xuất đặc tả khi cần.

Thử Apidog ngay hôm nay

Nếu bạn thuộc nhóm “spec-first”, Git thường là nguồn chân lý duy nhất. Đặc tả nằm trong thư mục như specs/, được review qua pull request, được lint trong CI, và có thể dùng để generate SDK hoặc tài liệu.

Nếu bạn thuộc nhóm “visual-first”, công cụ thiết kế giúp bắt đầu nhanh hơn, nhưng dễ phát sinh lệch giữa đặc tả trong công cụ và đặc tả trong repository.

Apidog trước đây phù hợp hơn với nhóm thứ hai. Trình thiết kế trực quan của nó mạnh, nhưng workflow ưu tiên đặc tả chưa thật sự tự nhiên. Điều đó thay đổi khi Apidog giới thiệu Chế độ Ưu tiên Đặc tả — Spec-First Mode Beta.

Bài viết này tập trung vào cách dùng chế độ mới theo hướng thực tế: tạo project, kết nối Git, chỉnh sửa OpenAPI, commit/push, và xác định khi nào nên dùng chế độ này trong team.

Chế độ Ưu tiên Đặc tả thay đổi điều gì?

Apidog hiện có hai kiểu project chính:

• Chế độ Chung: thiết kế API bằng form và giao diện trực quan. OpenAPI được tạo ra phía sau.
• Chế độ Ưu tiên Đặc tả: chỉnh sửa trực tiếp các file .yaml hoặc .json, đồng bộ hai chiều với Git repository.

Điểm quan trọng: trong Spec-First Mode, đặc tả OpenAPI là file thật trong repository của bạn. UI của Apidog chỉ là lớp làm việc phía trên file đó.

Bạn có:

• Trình soạn thảo code cho YAML/JSON.
• Tự động hoàn thành theo schema OpenAPI.
• Phân tích thư mục theo thời gian thực.
• Outline endpoint ở sidebar.
• Đồng bộ hai chiều với Git.
• Commit và push trực tiếp từ Apidog.

Điều này giải quyết một vấn đề quen thuộc của YAML: file đặc tả có thể dài, khó điều hướng, và dễ mất ngữ cảnh khi cuộn. Sidebar của Apidog tạo outline từ chính nội dung file, nên bạn vẫn làm việc theo kiểu spec-first nhưng có navigation giống công cụ trực quan.

Thiết lập Spec-First Mode từ đầu

Quy trình cơ bản gồm 6 bước.

1. Tạo project ở đúng chế độ

Trong Apidog, chọn:

+ Dự án Mới → Chung → Chế độ Ưu tiên Đặc tả

Lưu ý: Chế độ Chung thường được đánh dấu là “Đề xuất”, nên rất dễ bỏ qua ô Chế độ Ưu tiên Đặc tả. Nếu bạn muốn Git là nguồn chân lý, hãy chọn đúng chế độ ngay từ đầu.

Bạn không thể chuyển qua lại giữa hai chế độ trong cùng một project sau khi đã tạo.

2. Kết nối Git repository

Trong phần Kết nối với Kho lưu trữ Git, chọn nhà cung cấp Git và cấp quyền truy cập.

Sau đó chọn:

• Tổ chức
• Kho lưu trữ
• Nhánh chính

Ví dụ:

Organization: your-org
Repository: pet-store
Main branch: main

Apidog sẽ dùng repository đó làm nguồn chứa file đặc tả.

3. Cấu hình project

Nhập:

• Tên dự án
• Quyền truy cập của team
• Repository và branch đã chọn

Sau đó bấm Tạo.

Lần đồng bộ đầu tiên sẽ kéo các file .yaml và .json từ repository vào workspace Apidog.

4. Chỉnh sửa OpenAPI như code

Mở một file YAML hoặc JSON trong project.

Ví dụ một endpoint OpenAPI đơn giản:

paths:
  /pets:
    get:
      summary: List pets
      operationId: listPets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string

Khi bạn thêm hoặc sửa endpoint, sidebar sẽ cập nhật outline tương ứng. Bạn có thể nhấp vào endpoint trong sidebar để nhảy đến đúng vị trí trong file.

Nếu bạn từng dùng VS Code với extension OpenAPI, trải nghiệm này khá quen thuộc, nhưng có thêm workflow đồng bộ Git tích hợp sẵn trong Apidog.

5. Commit và push thay đổi

Sau khi chỉnh sửa, bấm:

Commit & Push

Hộp thoại sẽ hiển thị:

• Danh sách file thay đổi.
• Trường commit message.
• Nút Push.
• Nút Discard all changes.

Ví dụ commit message:

Add list pets endpoint

Không có bước staging riêng như trong Git CLI. File nào nằm trong phần Changes sẽ được đưa vào commit nếu được chọn.

6. Theo dõi trạng thái đồng bộ

Ở góc dưới bên trái, Apidog hiển thị trạng thái sync, ví dụ:

Synced just now

Chỉ báo này giúp bạn biết workspace hiện tại đang:

• Đã đồng bộ với remote.
• Có thay đổi local chưa push.
• Bị tụt phía sau remote.
• Cần pull thay đổi mới.

Trong workflow spec-first, đây là chi tiết quan trọng. Nếu Git là nguồn chân lý, bạn cần luôn biết trạng thái giữa editor và repository.

Một workflow thực tế nên dùng

Với team đã dùng OpenAPI trong Git, workflow có thể như sau:

1. Developer sửa openapi.yaml trong Apidog
2. Kiểm tra endpoint outline
3. Commit & Push lên branch chính hoặc branch làm việc
4. CI chạy lint/generate/test
5. Team review thay đổi trong Git

Nếu CI của bạn đang dùng spectral, có thể giữ nguyên bước lint hiện tại.

Ví dụ:

npx @stoplight/spectral-cli lint openapi.yaml

Hoặc trong package.json:

{
  "scripts": {
    "lint:api": "spectral lint openapi.yaml"
  }
}

Khi đó Apidog không thay thế CI. Nó thay thế bước chỉnh sửa và đồng bộ đặc tả thủ công.

Những điểm cần biết trước khi dùng

Sidebar cập nhật đủ nhanh để dùng như công cụ điều hướng

Một số editor OpenAPI chỉ parse lại file sau khi lưu. Điều đó tạo độ trễ giữa lúc thêm endpoint và lúc thấy endpoint trong outline.

Trong Spec-First Mode, outline của Apidog cập nhật khi bạn gõ. Điều này khiến sidebar trở thành một phần của workflow chỉnh sửa, không chỉ là báo cáo trạng thái.

Đồng bộ Git là hai chiều

Bạn có thể chỉnh sửa cùng repository từ bên ngoài Apidog, ví dụ bằng terminal hoặc VS Code.

Một workflow phổ biến:

git pull
# sửa openapi.yaml
git add openapi.yaml
git commit -m "Update auth schema"
git push

Khi Apidog đang mở, nó có thể nhận ra repository đã thay đổi và cho phép kéo thay đổi mới vào editor.

Điều này hữu ích nếu trong team có người thích dùng Vim/VS Code, còn người khác thích dùng Apidog. Miễn là tất cả cùng chỉnh sửa file trong Git, nguồn chân lý vẫn là một.

Không thể chuyển cùng một project về visual designer

Đây là điểm cần quyết định trước.

Nếu tạo project bằng Chế độ Ưu tiên Đặc tả, project đó là spec-first. Bạn không thể chuyển nó sang chế độ thiết kế trực quan trong cùng project.

Nếu team cần cả hai kiểu làm việc, cách thực tế hơn là:

- Giữ OpenAPI spec trong một Git repository.
- Tạo một project Spec-First trỏ vào repository đó.
- Nếu cần visual workflow, dùng project riêng nhập từ cùng nguồn đặc tả.

Cách này chưa liền mạch, nhưng tránh việc có hai phiên bản đặc tả không kiểm soát được.

Khi nào nên dùng Spec-First Mode?

Nên dùng nếu:

• Team đã viết OpenAPI bằng tay.
• OpenAPI spec cần nằm trong Git.
• CI đang lint đặc tả bằng công cụ như spectral.
• Bạn generate SDK, mock server, hoặc documentation từ spec.
• Bạn đang gặp vấn đề lệch giữa “spec trong công cụ” và “spec trong repository”.
• Developer muốn review API change bằng pull request.

Ví dụ cấu trúc repository phù hợp:

api/
  openapi.yaml
  spectral.yaml
  package.json
src/
  ...

Hoặc:

specs/
  public-api.yaml
  admin-api.yaml
docs/
  ...

Spec-First Mode phù hợp nhất khi file đặc tả là artifact chính của API lifecycle.

Khi nào không nên dùng?

Không nên dùng nếu:

• Team chưa quen OpenAPI.
• Người đóng góp chủ yếu cần form trực quan để tạo endpoint.
• Bạn muốn mọi thành viên không kỹ thuật cũng sửa API dễ dàng.
• Bạn cần kết hợp visual designer và spec editor trong cùng một project.

Trong các trường hợp đó, chế độ mặc định của Apidog vẫn phù hợp hơn. Nó giảm rào cản ban đầu và giúp người mới đóng góp mà không phải hiểu toàn bộ cấu trúc OpenAPI YAML.

Kết luận

Spec-first development không chỉ là “viết YAML”. Nó là cách tổ chức ownership của API: đặc tả nằm trong Git, được review, lint, version, và dùng làm đầu vào cho các bước tự động hóa.

Chế độ Ưu tiên Đặc tả của Apidog đưa workflow đó vào một công cụ API có editor, outline, và đồng bộ Git tích hợp. File trong repository vẫn là nguồn chân lý. Apidog trở thành môi trường làm việc phía trên file đó, không phải nơi tạo ra một bản sao riêng biệt.

Nếu team của bạn đã xem OpenAPI spec là artifact trung tâm, đây là chế độ đáng thử. Tạo project mới, chọn Chế độ Ưu tiên Đặc tả, kết nối repository, chỉnh sửa file YAML, rồi commit/push. Bạn sẽ biết khá nhanh liệu workflow này có phù hợp với team hay không.