Apidog Chế Độ Spec-First Là Gì

Apidog Spec-First Mode là không gian làm việc beta được xây dựng cho các nhóm coi tài liệu đặc tả OpenAPI của họ như mã nguồn. Bạn viết tài liệu đặc tả trực tiếp dưới dạng YAML hoặc JSON trong một trình chỉnh sửa kiểu IDE, sau đó đồng bộ hóa hai chiều với một kho lưu trữ Git đã kết nối. Không có trình chỉnh sửa dựa trên biểu mẫu nào nằm giữa bạn và tệp. Tài liệu đặc tả chính là dự án. Nếu bạn từng muốn chỉnh sửa openapi.yaml trong một trình soạn thảo mã thực sự và đẩy lên GitHub mà không cần rời khỏi công cụ API của mình, thì đây là chế độ dành cho bạn.

Hướng dẫn này là tài liệu tham khảo đầy đủ cho chính tính năng này. Nó bao gồm mọi khả năng, hướng dẫn thiết lập đầy đủ, đối tượng sử dụng, những hạn chế cần mong đợi từ một phiên bản beta và một phần FAQ thực tế. Để hiểu rõ hơn về ý tưởng đằng sau cách tiếp cận này, hãy xem quy trình làm việc API gốc Git của chúng tôi.

Chế độ Apidog Spec-First là gì?

Chế độ Spec-First là một chế độ chỉnh sửa beta trong Apidog, nơi thiết kế API của bạn tồn tại dưới dạng tài liệu OpenAPI thô. Bạn mở tệp, chỉnh sửa YAML hoặc JSON, xác thực, commit và đẩy lên Git. Apidog giữ cho tài liệu đặc tả và kho lưu trữ được đồng bộ hai chiều. Kéo thay đổi của đồng đội và trình chỉnh sửa của bạn sẽ cập nhật. Đẩy chỉnh sửa của bạn và kho lưu trữ sẽ cập nhật.

Nó được xây dựng dành riêng cho một loại nhóm: những người đã vận hành quy trình làm việc Git tự nhiên. Các kỹ sư backend, nhóm nền tảng và các cửa hàng ưu tiên API, những người quản lý phiên bản hợp đồng của họ trong các pull request sẽ cảm thấy quen thuộc. Tệp đặc tả trở thành nguồn đáng tin cậy duy nhất, và Git xử lý lịch sử, đánh giá và phân nhánh theo cách nó làm với phần còn lại của codebase của bạn.

Điều này khác với cách hầu hết các công cụ API hoạt động. Hầu hết các công cụ ẩn tài liệu đặc tả đằng sau một biểu mẫu đồ họa. Chế độ Spec-First hiển thị cho bạn tệp đó.

So sánh nhanh Chế độ Spec-First và Chế độ Design-First

Apidog cung cấp hai chế độ. Chế độ Design-First là trình chỉnh sửa dựa trên biểu mẫu, trực quan mà hầu hết các nhóm bắt đầu sử dụng. Chế độ Spec-First là cách tiếp cận trình chỉnh sửa mã mà hướng dẫn này đề cập. Dưới đây là phiên bản tóm tắt. Để biết phân tích đầy đủ về các đánh đổi, hãy đọc so sánh spec-first và design-first của chúng tôi.

Không có chế độ nào là "tốt hơn". Chúng phục vụ các nhóm khác nhau. Bạn có thể chuyển đổi giữa chúng, điều này chúng tôi sẽ đề cập bên dưới.

Các tính năng chính

Chế độ Spec-First không chỉ là một hộp văn bản. Nó tích hợp một trình chỉnh sửa, một trình điều hướng, tích hợp Git và các điều khiển nhóm. Dưới đây là mọi khả năng chi tiết.

Trình chỉnh sửa OpenAPI kiểu IDE

Trung tâm của không gian làm việc là một trình chỉnh sửa mã đầy đủ cho tài liệu OpenAPI của bạn. Bạn chỉnh sửa trực tiếp YAML hoặc JSON thô. Nó hoạt động giống như trình chỉnh sửa bạn đã sử dụng hàng ngày.

Bạn nhận được tính năng tô sáng cú pháp để tô màu các khóa, giá trị và cấu trúc giúp tệp luôn dễ đọc ở quy mô lớn. Bạn nhận được tính năng xác thực schema giúp đánh dấu lỗi so với đặc tả OpenAPI khi bạn nhập, do đó một đối tượng phản hồi bị định dạng sai hoặc một trường bắt buộc bị thiếu sẽ xuất hiện ngay lập tức. Bạn nhận được tính năng tự động hoàn thành được điều chỉnh cho OpenAPI và Swagger, đề xuất các từ khóa hợp lệ, tên trường và cấu trúc trong khi bạn viết.

Tính năng tự động hoàn thành đó đặc biệt quan trọng khi bạn đang làm việc sâu trong một schema và không thể nhớ liệu đó là additionalProperties hay additionalItems. Trình chỉnh sửa biết tài liệu đặc tả, vì vậy nó giúp bạn duy trì tính chính xác.

một phần nhỏ những gì bạn sẽ chỉnh sửa:

paths:
 /users/{userId}:
 get:
 summary: Get a user by ID
 operationId: getUserById
 parameters:
 - name: userId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: A single user
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'

Dàn ý điều hướng được tự động phân tích

Một tệp đặc tả thô sẽ nhanh chóng trở nên dài. Một API thực tế có thể có hàng nghìn dòng. Chế độ Spec-First giải quyết vấn đề đó bằng một thanh bên trái tự động phân tích tệp thành một dàn ý trực quan.

Khi bạn gõ, Apidog đọc tài liệu và xây dựng một cấu trúc có thể điều hướng: các đường dẫn, hoạt động, schema và thành phần. Nhấp vào bất kỳ nút nào trong dàn ý và trình chỉnh sửa sẽ nhảy đến vị trí đó trong tệp. Bạn điều hướng theo ý nghĩa, không phải bằng cách cuộn. Dàn ý cập nhật trực tiếp khi tài liệu đặc tả thay đổi, vì vậy nó luôn phản ánh những gì thực sự có trong tệp.

Điều này giúp quản lý một tệp openapi.yaml lớn. Bạn suy nghĩ theo khía cạnh "hoạt động POST /orders", chứ không phải "dòng 1.847".

Đồng bộ Git hai chiều

Đây là cốt lõi của chế độ này. Chế độ Spec-First kết nối với kho lưu trữ Git của bạn và đồng bộ hóa tài liệu đặc tả theo cả hai hướng.

GitHub và GitLab được hỗ trợ trực tiếp. Azure DevOps hoạt động thông qua Kết nối Git chung, cho phép bạn trỏ Apidog đến kho lưu trữ bằng cách sử dụng thông tin đăng nhập Git tiêu chuẩn. Sau khi được kết nối, việc kéo sẽ đưa các thay đổi của kho lưu trữ vào trình chỉnh sửa của bạn, và việc đẩy sẽ gửi các chỉnh sửa của bạn trở lại kho lưu trữ. Tài liệu đặc tả luôn nhất quán giữa mọi người trong nhóm vì Git là xương sống chung.

Nếu bạn muốn một hướng dẫn chi tiết, từng bước về một nhà cung cấp cụ thể, hướng dẫn đồng bộ tài liệu đặc tả OpenAPI với GitHub của chúng tôi sẽ hướng dẫn bạn quy trình đó.

Commit, push và chỉ báo trạng thái đồng bộ

Bạn không chỉ lưu và hy vọng. Chế độ Spec-First tuân theo mô hình Git mà bạn đã quen thuộc. Khi bạn hoàn thành chỉnh sửa, bạn viết một tin nhắn commit và commit thay đổi. Sau đó, bạn đẩy nó lên kho lưu trữ đã kết nối.

Một chỉ báo trạng thái đồng bộ sẽ thông báo cho bạn suốt thời gian. Nó hiển thị các trạng thái như "Đã đồng bộ ngay bây giờ" khi tài liệu đặc tả cục bộ của bạn khớp với kho lưu trữ và nó thay đổi khi bạn có công việc chưa được đẩy. Bạn luôn biết liệu phiên bản trước mặt bạn có phải là phiên bản mà đồng đội của bạn đang thấy hay không. Không cần đoán, không có tài liệu đặc tả lỗi thời.

Theo dõi thay đổi tệp

Trước khi bạn commit, Chế độ Spec-First hiển thị chính xác những gì đã thay đổi. Nó theo dõi các sửa đổi ở cấp độ tệp và đánh dấu mỗi mục là đã sửa đổi, đã thêm hoặc đã xóa. Bạn xem xét tập hợp các thay đổi theo cách bạn xem xét kết quả trạng thái Git.

Điều này quan trọng vì nó cung cấp cho bạn một điểm kiểm tra. Bạn có thể xác nhận rằng mình đang commit các chỉnh sửa đúng và không có gì thừa. Và nếu bạn quyết định một thử nghiệm không thành công, bạn có thể loại bỏ các chỉnh sửa chưa được đẩy trước khi chúng đến kho lưu trữ. Điều đó giữ cho lịch sử chia sẻ của bạn sạch sẽ. Việc khám phá cục bộ vẫn ở cục bộ cho đến khi bạn chọn đẩy nó.

Dự án có phạm vi chi nhánh và kho lưu trữ với quyền của nhóm

Một dự án Spec-First không phải là một thứ trừu tượng. Bạn tạo nó từ một kho lưu trữ và một nhánh cụ thể, thường là main. Phạm vi hóa đó có nghĩa là dự án luôn trỏ đến một vị trí thực trong Git. Tài liệu đặc tả, lịch sử và nhánh của bạn được sắp xếp.

Quyền của nhóm được cấu hình trong quá trình thiết lập. Bạn quyết định ai có thể truy cập dự án và họ có thể làm gì, để những người làm việc trên hợp đồng là những người bạn muốn. Vì dự án được gắn với một kho lưu trữ và nhánh, mô hình truy cập của bạn có thể phản ánh mô hình truy cập mà bạn đã áp dụng trong Git.

Cách thiết lập Chế độ Spec-First

Thiết lập là một quy trình ngắn gọn, tuyến tính. Thực hiện theo các bước sau. Hướng dẫn chính thức có tại docs.apidog.com/spec-first-mode-beta-2058268m0 nếu bạn muốn xem ảnh chụp màn hình kèm theo.

1. Chuyển chế độ. Mở mô-đun APIs trong Apidog. Tìm nút chuyển đổi chế độ ở phía dưới bên trái của mô-đun và chuyển từ Chế độ Design-First sang Chế độ Spec-First.
2. Kết nối nhà cung cấp Git của bạn. Ủy quyền trực tiếp GitHub hoặc GitLab. Đối với Azure DevOps, thiết lập Kết nối Git chung với thông tin đăng nhập Git của bạn.
3. Tạo một dự án từ kho lưu trữ của bạn. Chọn kho lưu trữ chứa tài liệu đặc tả của bạn và chọn nhánh, thường là main. Apidog sẽ giới hạn dự án mới vào kho lưu trữ và nhánh đó.
4. Cấu hình quyền của nhóm. Trong quá trình thiết lập, hãy đặt ai có thể truy cập dự án và những gì họ có thể thay đổi.
5. Chỉnh sửa tài liệu đặc tả. Mở openapi.yaml hoặc openapi.json của bạn trong trình chỉnh sửa kiểu IDE. Sử dụng dàn ý ở bên trái để điều hướng. Dựa vào xác thực và tự động hoàn thành khi bạn viết.
6. Commit các thay đổi của bạn. Viết một tin nhắn commit rõ ràng. Xem lại các thay đổi đã theo dõi trước. Loại bỏ bất cứ thứ gì bạn không muốn giữ lại.
7. Đẩy lên kho lưu trữ. Đẩy commit của bạn lên nhánh đã kết nối.
8. Xác minh đồng bộ. Kiểm tra chỉ báo trạng thái đồng bộ. Khi nó hiển thị "Đã đồng bộ ngay bây giờ", tài liệu đặc tả và kho lưu trữ của bạn khớp nhau.

Đó là toàn bộ quy trình: chuyển đổi, kết nối, tạo, chỉnh sửa, commit, đẩy, xác minh.

Quy trình làm việc hàng ngày điển hình

Đây là cảm giác của chế độ này trong thực tế sau khi đã thiết lập.

Bạn bắt đầu ngày của mình bằng cách kéo phiên bản mới nhất từ nhánh đã kết nối, để trình chỉnh sửa của bạn phản ánh những gì đồng đội của bạn đã hợp nhất qua đêm. Bạn mở dàn ý, nhấp vào hoạt động bạn đang làm việc và bắt đầu chỉnh sửa YAML. Một endpoint mới cần một request body, vì vậy bạn định nghĩa một schema. Tính năng tự động hoàn thành giúp bạn đặt tên trường đúng, và xác thực sẽ phát hiện lỗi đánh máy trong một $ref trước khi nó trở thành vấn đề.

Khi endpoint trông ổn, bạn kiểm tra tính năng theo dõi thay đổi tệp. Nó hiển thị các sửa đổi của bạn. Bạn viết một tin nhắn commit như Add POST /invoices endpoint, commit và đẩy. Chỉ báo trạng thái chuyển sang "Đã đồng bộ ngay bây giờ." Một đồng đội xem xét thay đổi trong một pull request thông thường, vì tài liệu đặc tả nằm trong Git giống như mọi thứ khác.

Đây là loại bổ sung bạn sẽ thực hiện trong quy trình đó:

components:
 schemas:
 Invoice:
 type: object
 required: [id, amount, currency]
 properties:
 id:
 type: string
 format: uuid
 amount:
 type: integer
 description: Amount in the smallest currency unit
 currency:
 type: string
 example: USD
 status:
 type: string
 enum: [draft, sent, paid]

Toàn bộ chu trình nằm trong các công cụ bạn tin cậy. Tài liệu đặc tả là mã, và bạn coi nó như mã.

Ai nên sử dụng Chế độ Spec-First

Chế độ Spec-First phù hợp với một số nhóm hơn những nhóm khác. Hãy thành thật về việc bạn thuộc nhóm nào.

Sử dụng Chế độ Spec-First nếu nhóm của bạn đã quen thuộc với Git. Nếu bạn xem xét các hợp đồng API trong pull request, nếu bạn muốn tài liệu đặc tả được quản lý phiên bản cạnh mã dịch vụ của mình, hoặc nếu các kỹ sư của bạn thích chỉnh sửa trực tiếp YAML, chế độ này sẽ loại bỏ sự phức tạp. Nó rất phù hợp cho các nhóm backend và nền tảng coi tài liệu OpenAPI như một tài liệu cấp cao.

Thay vào đó, hãy chọn Chế độ Design-First nếu bạn muốn một trải nghiệm trực quan, có hướng dẫn. Các nhóm có những người không phải là kỹ sư đóng góp vào thiết kế, hoặc bất kỳ ai thích nhấp qua các biểu mẫu hơn là viết YAML, sẽ làm việc nhanh hơn ở đó. Các nhóm hỗn hợp nơi sản phẩm và thiết kế đưa ra ý kiến về các endpoint thường thích trình chỉnh sửa trực quan. Không có câu trả lời sai. Hãy chọn chế độ phù hợp với cách nhóm của bạn thực sự làm việc. Bài viết so sánh của chúng tôi đi sâu hơn vào quyết định này.

Hạn chế và ghi chú về phiên bản beta

Chế độ Spec-First là phiên bản beta. Từ "beta" này có ý nghĩa thực sự, vì vậy hãy đặt kỳ vọng của bạn phù hợp.

Là một phiên bản beta, tính năng này vẫn đang trong quá trình hoàn thiện. Các khả năng và hành vi có thể thay đổi khi Apidog tinh chỉnh chế độ dựa trên phản hồi. Tích hợp trực tiếp nhà cung cấp hiện bao gồm GitHub và GitLab, trong khi Azure DevOps dựa vào Kết nối Git chung chứ không phải tích hợp chuyên dụng. Nếu nhóm của bạn phụ thuộc vào một nhà cung cấp Git hoặc quy trình làm việc cụ thể, hãy xác nhận rằng nó phù hợp với nhu cầu của bạn trước khi bạn cam kết một dự án quan trọng vào chế độ này.

Vì tài liệu đặc tả đồng bộ với một kho lưu trữ trực tiếp, kỷ luật Git thông thường được áp dụng. Commit một cách thận trọng, đẩy một cách có chủ đích và sử dụng tùy chọn loại bỏ khi một chỉnh sửa không nên được xuất bản. Tính năng theo dõi thay đổi tệp và chỉ báo đồng bộ có ở đó để giữ an toàn cho bạn, nhưng trách nhiệm về một lịch sử sạch sẽ vẫn là của bạn. Hãy đối xử với phiên bản beta theo cách bạn đối xử với bất kỳ công cụ mới nào tác động đến nhánh chính của bạn: hãy thử nó trên một kho lưu trữ không quan trọng trước, sau đó mở rộng khi bạn tin tưởng vào quy trình.

Ưu điểm của một phiên bản beta là khả năng tác động. Phản hồi sớm định hình hướng phát triển của tính năng, vì vậy nếu có điều gì đó thiếu sót cho quy trình làm việc của bạn, điều đó đáng để báo cáo.

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

Chế độ Spec-First có miễn phí không?

Chế độ Spec-First là một tính năng beta bên trong Apidog. Quyền truy cập tuân theo gói Apidog của bạn, vì vậy hãy kiểm tra tính khả dụng của chế độ so với gói hiện tại và trạng thái beta. Vì nó đang ở phiên bản beta, cách đơn giản nhất là bật nó trong mô-đun APIs và xem liệu nó có khả dụng cho tài khoản của bạn hay không.

Các nhà cung cấp Git nào được hỗ trợ?

GitHub và GitLab được hỗ trợ thông qua tích hợp trực tiếp. Azure DevOps hoạt động thông qua Kết nối Git chung, sử dụng thông tin đăng nhập Git tiêu chuẩn để trỏ Apidog đến kho lưu trữ của bạn. Các máy chủ Git khác cũng có thể hoạt động thông qua kết nối chung đó, vì nó dựa vào Git tiêu chuẩn chứ không phải API dành riêng cho nhà cung cấp.

Tôi có thể chuyển lại sang Chế độ Design-First không?

Có. Nút chuyển đổi chế độ nằm ở phía dưới bên trái của mô-đun APIs, và bạn chuyển đổi giữa Spec-First và Design-First ở đó. Bạn không bị khóa. Hãy chọn chế độ phù hợp với dự án bạn đang làm.

Tôi có thể chỉnh sửa những định dạng tệp nào?

Bạn chỉnh sửa tài liệu OpenAPI của mình dưới dạng YAML hoặc JSON thô trong trình chỉnh sửa kiểu IDE. Trình chỉnh sửa cung cấp tính năng tô sáng cú pháp, xác thực schema và tự động hoàn thành cho cả OpenAPI và Swagger, vì vậy bạn duy trì tính chính xác khi viết ở bất kỳ định dạng nào.

Điều gì xảy ra với các chỉnh sửa chưa được đẩy của tôi?

Các chỉnh sửa chưa được đẩy vẫn ở cục bộ cho đến khi bạn đẩy chúng. Chế độ Spec-First theo dõi mọi thay đổi dưới dạng đã sửa đổi, đã thêm hoặc đã xóa, và chỉ báo đồng bộ hiển thị khi bạn có công việc chưa đến kho lưu trữ. Nếu bạn quyết định không thực hiện thay đổi, hãy loại bỏ nó trước khi đẩy và nó sẽ không bao giờ đi vào lịch sử chia sẻ của bạn.

Kết luận

Chế độ Apidog Spec-First tích hợp trình chỉnh sửa OpenAPI và Git vào một nơi. Bạn chỉnh sửa tài liệu đặc tả dưới dạng YAML hoặc JSON, điều hướng nó thông qua một dàn ý được tự động phân tích, xác thực khi bạn gõ và đồng bộ hóa hai chiều với GitHub, GitLab hoặc Azure DevOps. Tin nhắn commit, push, theo dõi thay đổi và một chỉ báo đồng bộ rõ ràng mang đến cho bạn quy trình làm việc Git mà bạn đã biết, được áp dụng cho hợp đồng API của bạn.

Đây là phiên bản beta, và nó nhắm đến các nhóm ưu tiên Git muốn coi tài liệu đặc tả là mã nguồn. Nếu đó là bạn, chế độ này rất đáng để xem xét nghiêm túc. Hãy bật nó trong mô-đun APIs, kết nối một kho lưu trữ và thử một chu trình chỉnh sửa-commit-push nhỏ để cảm nhận quy trình. Khi bạn sẵn sàng, hãy thử Chế độ Spec-First trong tài liệu và kết nối nó với một kho lưu trữ mà bạn tin cậy.

nút