Cách thiết kế API từ CLI

Thiết kế API từ dòng lệnh: tạo, kiểm tra, đóng gói và tự động hóa

Hầu hết hướng dẫn thiết kế API bắt đầu bằng thao tác chuột: mở trình soạn thảo trực quan, kéo lược đồ lên canvas và thêm trường qua hộp thoại. Cách này vẫn hiệu quả, nhưng không phù hợp với nhóm lưu định nghĩa API trong Git, review qua pull request và chạy CI. Trong mô hình đó, API nên được thiết kế như cách bạn triển khai nó: từ terminal, dưới dạng văn bản và bằng các lệnh có thể script hóa.

Dùng thử Apidog ngay hôm nay

Thiết kế API bằng CLI cho phép bạn tạo hợp đồng, lint theo quy ước, đóng gói thành một tệp duy nhất và sinh mã mà không rời shell. Mỗi bước có thể lặp lại, đưa vào pipeline và tái tạo bởi đồng đội hoặc tác nhân AI mà không cần đoán các thao tác GUI.

Bài viết này trình bày hai hướng triển khai:

1. Bộ công cụ mã nguồn mở: OpenAPI + Spectral + Redocly CLI + openapi-generator.
2. Apidog CLI: quản lý schema, endpoint, xác thực, import/export trong cùng một dự án.

Nếu cần nền tảng trước khi bắt đầu, hãy xem cách thiết kế API và hướng dẫn về thiết kế API REST.

Nếu dùng Apidog, hãy cài CLI và đăng nhập trước. Hướng dẫn cài đặt Apidog CLI trình bày chi tiết bước cài đặt và xác thực token; hướng dẫn Apidog CLI đầy đủ liệt kê các nhóm lệnh có sẵn.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Con đường mã nguồn mở: tạo, lint, đóng gói, sinh mã

Đây là quy trình Git-native cổ điển: lưu đặc tả OpenAPI trong repository và chạy từng công cụ ở một bước riêng. Cách tiếp cận này phù hợp khi bạn muốn kiểm soát hoàn toàn cấu trúc tệp, rule lint và cấu hình sinh mã.

Đây cũng là nền tảng của quy trình thiết kế API tích hợp Git.

1. Tạo tài liệu OpenAPI

Bắt đầu bằng một tệp openapi.yaml. Không cần trình soạn thảo chuyên dụng; bất kỳ editor văn bản nào cũng đủ.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

Khi API lớn hơn, tách schema, path và response thành các tệp riêng rồi liên kết bằng $ref. Ví dụ:

# paths/orders.yaml
get:
  operationId: getOrder
  responses:
    '200':
      $ref: '../responses/order.yaml'

Việc chia tệp giúp pull request dễ review hơn, nhưng bạn sẽ cần đóng gói lại trước khi đưa đặc tả cho code generator hoặc công cụ tài liệu.

2. Kiểm tra cú pháp và quy ước với Spectral

OpenAPI viết thủ công dễ phát sinh lỗi: thiếu operationId, response không có mô tả, tên trường không nhất quán hoặc endpoint không tuân theo quy ước nhóm.

Cài Spectral:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Spectral trả về vị trí dòng, mức độ nghiêm trọng và rule bị vi phạm. Trong CI, mã thoát khác 0 có thể làm thất bại pipeline.

Ví dụ một cấu hình .spectral.yaml tối thiểu:

extends:
  - spectral:oas

rules:
  operation-operationId:
    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
    then:
      field: operationId
      function: truthy

Chạy lint với rule tùy chỉnh:

spectral lint openapi.yaml --ruleset .spectral.yaml

Bạn cũng có thể dùng Redocly CLI hoặc vacuum nếu phù hợp với stack hiện tại. Điểm quan trọng là lint phải là một bước độc lập, có thể chạy cục bộ và trong CI.

3. Đóng gói đặc tả với Redocly CLI

Khi đặc tả có nhiều $ref, hầu hết công cụ hạ nguồn sẽ cần một tài liệu tự chứa duy nhất. Redocly CLI giải quyết các tham chiếu và xuất một tệp đã được đóng gói.

npm install -g @redocly/cli
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

Sau bước này, dist/openapi.bundled.yaml là artifact phù hợp để:

• Sinh SDK hoặc server stub.
• Xuất bản tài liệu.
• Lưu làm artifact của pipeline.
• Đưa vào kiểm thử hợp đồng.

Redocly CLI cũng hỗ trợ lint:

redocly lint openapi.yaml

Xem thêm trong tài liệu Redocly CLI.

4. Sinh server stub và SDK với openapi-generator

Khi đã có đặc tả sạch và được đóng gói, dùng openapi-generator để sinh mã.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server

Thay spring bằng generator phù hợp với backend của bạn:

# Python Flask
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g python-flask \
  -o ./server

# Go server
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g go-server \
  -o ./server

Quy trình mã nguồn mở hoàn chỉnh:

spectral lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server

Ưu điểm là quyền kiểm soát tối đa và không bị khóa vào một nền tảng. Đổi lại, nhóm phải tự duy trì cấu trúc tệp, rule lint, bước bundle và cấu hình generator.

Con đường Apidog CLI: thiết kế trong một dự án

Apidog CLI tập trung schema, endpoint, thư mục tổ chức, xác thực, import/export và mock trong một dự án. Thay vì ghép nhiều công cụ riêng lẻ, bạn quản lý tài nguyên API từ terminal bằng các nhóm lệnh như:

• schema
• endpoint
• folder
• security-scheme
• import
• export
• mock

Một điểm cần phân biệt rõ: Apidog không thay thế OpenAPI linter. Nếu cần kiểm tra style guide hoặc rule OpenAPI, vẫn dùng Spectral hoặc vacuum. Apidog CLI quản lý tài nguyên dự án và xác thực cấu trúc tài nguyên CLI.

Apidog là sản phẩm thương mại có gói miễn phí, không phải công cụ mã nguồn mở. Cách đánh đổi này có thể phù hợp nếu nhóm muốn giảm công sức kết nối các phần của quy trình thiết kế. Xem thêm bài viết về các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API.

Mọi lệnh CLI trả về JSON có cấu trúc. Nhiều phản hồi gồm agentHints.nextSteps, giúp script hoặc tác nhân AI xác định lệnh tiếp theo mà không cần phụ thuộc GUI.

Dùng --help để xem cờ và tham số chính xác:

apidog --help
apidog schema --help
apidog endpoint --help

1. Định nghĩa mô hình dữ liệu với apidog schema

Thiết kế bắt đầu từ dữ liệu. Một schema Order dùng lại được sẽ trở thành nguồn chân lý duy nhất cho nhiều endpoint, tương tự components/schemas trong OpenAPI.

apidog schema --help
apidog schema create --project <PROJECT_ID>

Vì kết quả là JSON, bạn có thể dùng jq để lấy ID và truyền sang bước sau:

apidog schema create --project <PROJECT_ID> | jq -r '.data.id'

Nếu đã có OpenAPI, import trực tiếp thay vì tạo lại thủ công:

apidog import --project <PROJECT_ID> --file openapi.yaml

apidog import hỗ trợ OpenAPI 3.x, Swagger 2.0, Postman và định dạng Apidog. Đây là cách nhanh nhất để chuyển một API hiện có thành dự án có thể quản lý bằng CLI.

2. Định nghĩa endpoint với apidog endpoint

Sau khi có schema, tạo hoặc cập nhật endpoint bằng nhóm lệnh endpoint.

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>

Lệnh liệt kê endpoint trả về JSON nên có thể dùng trong script kiểm tra. Ví dụ, lưu danh sách endpoint để so sánh giữa các nhánh:

apidog endpoint list --project <PROJECT_ID> \
  | jq '.' > dist/endpoints.json

Bạn cũng có thể kiểm tra một path mong đợi có tồn tại hay không:

apidog endpoint list --project <PROJECT_ID> \
  | jq -e '.data[] | select(.path == "/orders/{orderId}")' > /dev/null

Khi số lượng endpoint tăng, dùng nhóm lệnh folder để tổ chức tài nguyên theo domain hoặc module.

3. Định nghĩa xác thực với apidog security-scheme

Xác thực là một phần của hợp đồng API. Thay vì khai báo lặp lại trên từng endpoint, định nghĩa tập trung ở cấp độ dự án bằng security-scheme.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>

Khái niệm này tương ứng với components/securitySchemes của OpenAPI. Khi import hoặc export, cấu trúc xác thực có thể được chuyển đổi cùng với đặc tả.

Lợi ích chính là tính nhất quán: các endpoint tham chiếu cùng một scheme thay vì tự khai báo API key, bearer token hoặc OAuth 2.0 theo nhiều cách khác nhau.

4. Xác thực tài nguyên CLI với apidog cli-schema validate

Trước khi commit thay đổi hoặc áp dụng tài nguyên vào dự án, xác thực tệp định nghĩa theo schema mà CLI mong đợi.

apidog cli-schema --help
apidog cli-schema validate --file resource.json

Đặt bước này trước thao tác áp dụng tài nguyên:

apidog cli-schema validate --file resource.json

# Chỉ chạy bước tiếp theo nếu validate thành công
# apidog <lệnh áp dụng tài nguyên>

Mã thoát khác 0 sẽ dừng pipeline sớm khi tệp tài nguyên sai định dạng.

Lưu ý: apidog cli-schema validate không phải OpenAPI lint. Nó xác thực cấu trúc của tài nguyên CLI, không kiểm tra style guide, operationId hoặc quy ước đặt tên OpenAPI.

5. Xuất dự án về OpenAPI

Sau khi thiết kế trong Apidog, xuất lại artifact tiêu chuẩn để dùng trong các công cụ khác.

mkdir -p dist

apidog export \
  --project <PROJECT_ID> \
  --format openapi \
  -o dist/openapi.yaml

Tệp xuất có thể tiếp tục đi qua các bước lint, bundle và code generation:

spectral lint dist/openapi.yaml

redocly bundle \
  dist/openapi.yaml \
  -o dist/openapi.bundled.yaml

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server

Apidog CLI và bộ công cụ OpenAPI mã nguồn mở không loại trừ nhau. apidog export là cầu nối giữa hai hướng làm việc.

Đưa quy trình vào CI

Cả hai hướng đều phù hợp với CI vì các lệnh có đầu ra văn bản và mã thoát rõ ràng.

Ví dụ một script kiểm tra thiết kế:

#!/usr/bin/env bash
set -euo pipefail

# Kiểm tra OpenAPI style và rule
spectral lint openapi.yaml

# Kiểm tra tệp tài nguyên CLI trước khi áp dụng
apidog cli-schema validate --file resource.json

# Đóng gói đặc tả thành artifact duy nhất
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

Ví dụ GitHub Actions tối thiểu:

name: API contract checks

on:
  pull_request:
    paths:
      - "openapi/**"
      - "openapi.yaml"
      - "resource.json"

jobs:
  validate-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install tools
        run: |
          npm install -g @stoplight/spectral-cli
          npm install -g @redocly/cli
          npm install -g apidog-cli

      - name: Lint OpenAPI
        run: spectral lint openapi.yaml

      - name: Validate CLI resource
        run: apidog cli-schema validate --file resource.json

      - name: Bundle OpenAPI
        run: redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

Với đầu ra JSON và agentHints.nextSteps, Apidog CLI cũng phù hợp cho luồng tự động do tác nhân AI điều khiển. Tác nhân có thể đọc phản hồi có cấu trúc, xác định bước kế tiếp và thực thi nó từ shell.

Những vướng mắc thường gặp

Các tệp $ref làm hỏng công cụ hạ nguồn

Chia đặc tả thành nhiều tệp giúp con người dễ làm việc, nhưng code generator và công cụ tài liệu thường cần một tệp tự chứa.

Luôn bundle trước khi sinh mã hoặc xuất bản tài liệu:

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

Mong đợi Apidog lint OpenAPI

Apidog quản lý tài nguyên dự án, không thực thi style guide OpenAPI hoặc rule đặt tên. Giữ Spectral hoặc vacuum trong pipeline nếu cần lint.

spectral lint openapi.yaml
apidog cli-schema validate --file resource.json

Hai lệnh trên kiểm tra hai vấn đề khác nhau và thường nên cùng tồn tại.

Quên import API hiện có trước khi chỉnh sửa

Nếu API đã tồn tại dưới dạng OpenAPI hoặc Swagger, hãy import nó vào dự án trước:

apidog import --project <PROJECT_ID> --file openapi.yaml

Chỉnh sửa một dự án trống rồi kỳ vọng endpoint cũ xuất hiện sẽ gây nhầm lẫn và có thể dẫn đến mất thời gian tái tạo tài nguyên.

Khai báo xác thực lặp lại trên từng endpoint

Định nghĩa security-scheme một lần ở cấp dự án và để các endpoint tham chiếu lại. Khai báo auth riêng trên từng operation dễ tạo ra sai lệch giữa các hợp đồng.

Tổng kết

Thiết kế API từ CLI biến quy trình phụ thuộc vào thao tác chuột thành các lệnh có thể lặp lại, review, script hóa và chạy trong CI.

Con đường mã nguồn mở gồm:

spectral lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
openapi-generator-cli generate -i dist/openapi.bundled.yaml -g spring -o ./server

Con đường Apidog CLI cung cấp dự án tích hợp để quản lý schema, endpoint và xác thực từ terminal, sau đó xuất OpenAPI để tiếp tục dùng với Spectral, Redocly hoặc openapi-generator.

Chọn cách phù hợp với nhóm:

• Nếu đã làm việc theo Git với các công cụ đơn mục đích, giữ nguyên stack và chuẩn hóa artifact OpenAPI đã bundle.
• Nếu muốn quản lý tài nguyên API trong một dự án tích hợp, hãy tải xuống Apidog, cài CLI và đưa các thao tác thiết kế vào terminal.