Hầu hết các hướng dẫn thiết kế API bắt đầu bằng chuột. Mở một trình soạn thảo trực quan, kéo một lược đồ lên canvas, nhấp qua các hộp thoại để thêm một trường. Điều đó hoạt động, nhưng nó không phù hợp với cách nhiều nhóm thực sự triển khai. Nếu định nghĩa API của bạn nằm trong Git, được xem xét trong các yêu cầu kéo (pull requests), và đi qua CI, bạn muốn thiết kế nó theo cùng một cách bạn triển khai nó: từ terminal, dưới dạng văn bản, với các lệnh bạn có thể viết script.
Thiết kế API từ dòng lệnh có nghĩa là bạn tạo hợp đồng, kiểm tra cú pháp (lint) nó theo hướng dẫn kiểu dáng, đóng gói nó thành một tệp duy nhất và tạo ra các đoạn mã (stubs), tất cả mà không cần rời khỏi shell. Mọi bước đều có thể lặp lại. Mọi bước đều có thể chạy trong một quy trình (pipeline). Và khi một tác nhân AI hoặc đồng đội cần tái tạo thiết lập của bạn, họ sẽ chạy các lệnh giống như bạn đã làm thay vì phải đoán xem bạn đã nhấp vào nút nào.
Hướng dẫn này trình bày hai con đường. Thứ nhất, con đường mã nguồn mở chung được xây dựng từ các công cụ đơn mục đích: tạo tệp OpenAPI, kiểm tra cú pháp với Spectral, đóng gói nó với Redocly CLI và tạo các đoạn mã máy chủ (server stubs) với openapi-generator. Sau đó là con đường Apidog CLI, nơi thiết kế, lược đồ, điểm cuối và xác thực nằm trong một dự án bạn có thể điều khiển từ terminal. Nếu bạn muốn tìm hiểu nền tảng khái niệm sâu hơn trước, hãy đọc hướng dẫn của chúng tôi về cách thiết kế API và hướng dẫn chi tiết về thiết kế API REST.
Nếu bạn đang làm theo với Apidog, hãy tải tệp nhị phân trước. Hướng dẫn cài đặt Apidog CLI của chúng tôi bao gồm bước npm install -g apidog-cli và quá trình bắt tay apidog login --with-token, còn hướng dẫn Apidog CLI đầy đủ sẽ liệt kê mọi nhóm lệnh.
Con đường mã nguồn mở chung: tạo, kiểm tra cú pháp, đóng gói, tạo mã
Bộ công cụ thiết kế CLI cổ điển là một tập hợp các công cụ độc lập mà bạn kết nối với nhau. Bạn giữ định nghĩa API của mình trong một tệp OpenAPI dưới sự kiểm soát phiên bản và chạy từng công cụ như một bước. Đây là quy trình làm việc thiết kế API tích hợp Git, và nó thực sự tốt. Dưới đây là hình thức của nó.
Tạo tài liệu OpenAPI
Bạn bắt đầu với một tệp YAML đơn giản. Không cần trình soạn thảo đặc biệt nào; bất kỳ trình soạn thảo văn bản nào cũng hoạt động. Một openapi.yaml tối thiểu trông như thế này:
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 phát triển, bạn chia nó thành nhiều tệp và tham chiếu chúng bằng $ref. Điều đó giúp mỗi lược đồ dễ đọc và dễ xem xét riêng biệt.
Kiểm tra cú pháp với Spectral
OpenAPI viết thủ công thường bị sai lệch. Ai đó quên một operationId, người khác để một phản hồi không được ghi lại, người thứ ba lại tự tạo quy ước đặt tên riêng của họ. Một trình kiểm tra cú pháp (linter) sẽ bắt được tất cả những lỗi đó trước khi xem xét. Spectral, từ Stoplight, là lựa chọn tiêu chuẩn. Nó cung cấp các bộ quy tắc cho OpenAPI và cho phép bạn tự viết các quy tắc của mình.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral in ra mọi vi phạm cùng với số dòng và mức độ nghiêm trọng. Bạn có thể làm thất bại bản dựng (build) khi có lỗi bằng cách kiểm tra mã thoát trong CI. Redocly CLI và vacuum cũng làm công việc tương tự nếu bạn muốn một lựa chọn thay thế; vacuum nhanh và có thể thay thế dễ dàng như một trình kiểm tra cú pháp tương thích với Spectral. Dù bạn chọn công cụ nào thì điểm mấu chốt vẫn là: kiểm tra cú pháp là một công cụ riêng biệt, chuyên dụng và bạn chạy nó như một bước độc lập.
Đóng gói với Redocly CLI
Khi định nghĩa của bạn được chia thành nhiều tệp, hầu hết các công cụ hạ nguồn đều muốn một tài liệu tự chứa duy nhất. Redocly CLI giải quyết mọi $ref và làm phẳng cây thành một tệp.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly cũng kiểm tra cú pháp (redocly lint) và xem trước tài liệu, vì vậy một số nhóm sử dụng nó cho cả việc kiểm tra kiểu dáng và đóng gói. Tài liệu chính thức của nó liệt kê toàn bộ tập lệnh lệnh.
Tạo các đoạn mã với openapi-generator
Với một đặc tả sạch sẽ, đã được đóng gói, bạn có thể tạo mã. openapi-generator biến một tài liệu OpenAPI thành các đoạn mã máy chủ (server stubs), SDK máy khách (client SDKs) và nhiều thứ khác trên hàng chục ngôn ngữ.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Thay thế -g spring bằng -g python-flask, -g go-server, hoặc bất kỳ trình tạo nào được hỗ trợ. Giờ đây bạn đã có khung sườn phù hợp chính xác với hợp đồng của mình.
Đó là con đường mở từ đầu đến cuối: bốn công cụ, bốn lệnh, tất cả đều có thể viết script. Cái giá phải trả là việc kết nối. Bạn tự mình duy trì bố cục tệp, cấu hình linter, bước đóng gói và cấu hình trình tạo, và mỗi công cụ có các quy ước riêng của nó. Nó hoạt động tốt khi bạn muốn kiểm soát tối đa và không ngại việc kết nối các phần lại với nhau.
Con đường Apidog CLI: thiết kế trong một dự án
Cách tiếp cận khác là giữ thiết kế, lược đồ, điểm cuối, mô phỏng và xác thực bên trong một dự án duy nhất mà bạn điều khiển từ terminal. Tệp nhị phân apidog-cli là một CLI tài nguyên dự án hoàn chỉnh, không chỉ là một trình chạy thử nghiệm. Nó có các nhóm lệnh cho toàn bộ bề mặt thiết kế: schema cho các mô hình dữ liệu, endpoint cho các hoạt động, folder để tổ chức, security-scheme cho xác thực, cộng với import, export, mock, và nhiều hơn nữa.
Một lưu ý thẳng thắn ngay từ đầu: Apidog không kiểm tra cú pháp OpenAPI của bạn hay thực thi một hướng dẫn kiểu dáng. Đó không phải là mục đích của nó. Nếu bạn cần kiểm tra cú pháp, hãy giữ Spectral hoặc vacuum trong quy trình của bạn. Apidog cũng không phải là mã nguồn mở; nó là một sản phẩm thương mại có một gói miễn phí. Những gì nó mang lại cho bạn là một dự án tích hợp để bạn không phải tự mình ghép nối các phần thiết kế lại với nhau. Quan điểm của chúng tôi về các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API bao gồm những trường hợp mà sự đánh đổi đó có ý nghĩa.
Cài đặt và xác thực trước (xem hướng dẫn cài đặt để thiết lập token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Mọi lệnh đều trả về JSON có cấu trúc, và hầu hết các phản hồi đều bao gồm một khối agentHints.nextSteps cho bạn (hoặc một tác nhân) biết nên chạy gì tiếp theo. Thêm --help vào bất kỳ lệnh nào để xem các cờ chính xác của nó.
Định nghĩa mô hình dữ liệu với apidog schema
Thiết kế bắt đầu bằng dữ liệu của bạn. Một lược đồ Order có thể tái sử dụng trở thành nguồn chân lý duy nhất mà các điểm cuối tham chiếu, cùng một ý tưởng như components/schemas trong OpenAPI thô, nhưng được quản lý như một tài nguyên dự án.
apidog schema --help
apidog schema create --project <PROJECT_ID>
Vì đầu ra là JSON, bạn có thể truyền nó qua jq để lấy ID của lược đồ mới và đưa vào lệnh tiếp theo. Nếu bạn đã có tệp OpenAPI, hãy nhập nó thay vì gõ lại mọi thứ:
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog import chấp nhận các định dạng OpenAPI 3.x, Swagger 2.0, Postman và Apidog, do đó một định nghĩa hiện có trở thành một dự án hoạt động chỉ trong một bước.
Định nghĩa điểm cuối với apidog endpoint
Khi các mô hình đã có sẵn, bạn thêm các hoạt động. Nhóm endpoint tạo và cập nhật các điểm cuối, kết nối chúng với các lược đồ bạn đã định nghĩa và với các thư mục tổ chức chúng.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Liệt kê các điểm cuối dưới dạng JSON tự nó đã hữu ích. Bạn có thể so sánh sự khác biệt của đầu ra giữa các nhánh hoặc đưa nó vào một script kiểm tra xem mọi đường dẫn có các phản hồi bạn mong đợi hay không. Nhóm các điểm cuối liên quan bằng lệnh folder để dự án vẫn dễ điều hướng khi nó phát triển.
Đị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, không phải là một điều nghĩ sau. Nhóm security-scheme định nghĩa cách các máy khách xác thực: khóa API, token bearer, OAuth 2.0, v.v. Điều này ánh xạ tới components/securitySchemes trong OpenAPI, vì vậy việc nhập và xuất sẽ diễn ra sạch sẽ.
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Việc định nghĩa lược đồ một lần ở cấp độ dự án có nghĩa là mọi điểm cuối có thể tham chiếu nó thay vì mỗi hoạt động phải khai báo lại xác thực riêng của mình. Đó chính xác là loại tính nhất quán mà một trình kiểm tra cú pháp sẽ nhắc nhở bạn nếu không có.
Xác thực các ghi chép của bạn với apidog cli-schema validate
Trước khi bạn cam kết thay đổi hoặc giao một dự án cho CI, bạn muốn biết các định nghĩa tài nguyên của mình đã được định dạng tốt. CLI cung cấp một lệnh cli-schema validate để kiểm tra một tệp định nghĩa so với lược đồ mà CLI mong đợi, vì vậy một ghi chép không đúng định dạng sẽ thất bại nhanh chóng thay vì âm thầm được chấp nhận.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Chạy lệnh này như một bước bảo vệ trong quy trình của bạn: xác thực trước, sau đó áp dụng. Mã thoát khác 0 sẽ dừng quy trình trước khi một tài nguyên xấu được đưa vào dự án. Đây là việc xác thực các ghi chép CLI của bạn, không phải kiểm tra cú pháp theo kiểu OpenAPI; đó là hai công việc khác nhau, và bạn vẫn muốn Spectral cho công việc thứ hai.
Xuất trở lại OpenAPI
Thiết kế trong Apidog, sau đó chuyển một hiện vật tiêu chuẩn cho phần còn lại của chuỗi công cụ của bạn. apidog export ghi ra định dạng OpenAPI, HTML, Markdown hoặc Postman.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Giờ đây bạn đã trở lại với một tệp OpenAPI di động. Đưa nó cho Spectral để kiểm tra cú pháp, cho openapi-generator để tạo các đoạn mã, hoặc vào quy trình xây dựng tài liệu của bạn. Dự án tích hợp và bộ công cụ mở không loại trừ lẫn nhau; xuất là cầu nối giữa chúng.
Kết nối nó vào CI
Cả hai con đường đều tỏa sáng trong một quy trình vì mỗi lệnh đều có mã thoát và đầu ra văn bản. Một công việc kiểm tra thiết kế tối thiểu có thể chạy trình kiểm tra cú pháp, sau đó xác thực, rồi đóng gói:
# fail on style violations
spectral lint openapi.yaml
# validate any CLI resource writes before applying
apidog cli-schema validate --file resource.json
# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Vì đầu ra của Apidog là JSON với agentHints.nextSteps, luồng này cũng có thể được điều khiển một cách sạch sẽ từ một tác nhân AI lập trình. Tác nhân đọc kết quả có cấu trúc, thấy bước tiếp theo được đề xuất và chạy nó, không cần quét màn hình GUI. Đó chính là lý do để thiết kế từ CLI ngay từ đầu: những gì con người gõ, một script hoặc một tác nhân cũng có thể gõ được.
Những vướng mắc thường gặp
Các tệp bị chia nhỏ làm hỏng các công cụ hạ nguồn. Một định nghĩa trải rộng trên nhiều tệp $ref rất tốt cho con người nhưng lại khó xử đối với các trình tạo mã. Luôn đóng gói thành một tệp duy nhất trước khi bạn tạo mã hoặc xuất bản tài liệu. redocly bundle là giải pháp khắc phục.
Bạn mong đợi Apidog sẽ kiểm tra cú pháp. Nó sẽ không làm vậy. Apidog quản lý tài nguyên; nó không thực thi hướng dẫn kiểu dáng hay gắn cờ các vi phạm quy tắc OpenAPI. Hãy giữ Spectral hoặc vacuum trong vòng lặp cho việc đó. Nhầm lẫn apidog cli-schema validate với một trình kiểm tra cú pháp là một lỗi phổ biến; nó xác thực cấu trúc tài nguyên, chứ không phải kiểu dáng OpenAPI.
Quên nhập khẩu trước khi chỉnh sửa. Nếu bạn đang chỉnh sửa một API hiện có thông qua CLI, hãy nhập định nghĩa nguồn vào dự án trước. Chỉnh sửa một dự án trống rỗng và mong đợi các điểm cuối cũ của bạn ở đó là một cách nhanh chóng để bị nhầm lẫn.
Xác thực được định nghĩa cho từng điểm cuối thay vì một lần. Định nghĩa một security-scheme ở cấp độ dự án và tham chiếu nó. Việc khai báo lại xác thực trên mọi hoạt động là cách các hợp đồng bị sai lệch.
Tổng kết
Thiết kế API từ CLI biến một tác vụ nặng về nhấp chuột thành một tập hợp các lệnh có thể lặp lại. Con đường mở, tạo, kiểm tra cú pháp với Spectral, đóng gói với Redocly, tạo mã với openapi-generator, mang lại cho bạn toàn quyền kiểm soát và không bị khóa. Con đường Apidog CLI cung cấp cho bạn một dự án tích hợp nơi các lược đồ, điểm cuối và xác thực sống cùng nhau và mọi lệnh đều trả về JSON sẵn sàng cho tác nhân. Chức năng xuất là cầu nối giữa hai con đường, vì vậy bạn sẽ không bao giờ bị mắc kẹt.
Hãy chọn con đường phù hợp với nhóm của bạn. Nếu bạn đã quen làm việc trong Git với một đống công cụ đơn mục đích, hãy giữ chúng và thêm apidog export khi bạn muốn một hiện vật di động. Nếu bạn không muốn duy trì các kết nối, hãy tải xuống Apidog, cài đặt CLI và thiết kế API tiếp theo của bạn mà không cần chạm vào chuột.