Có hai trường phái trong mọi đội ngũ API mà tôi từng làm việc cùng.
Một bên tự viết đặc tả OpenAPI bằng tay, commit nó vào thư mục specs/, và coi Git là nguồn chân lý duy nhất. Bên còn lại nhấp chuột qua một trình thiết kế trực quan, xuất đặc tả khi CI phàn nàn, và vá lỗi những sai lệch mà hai phiên bản đã tích lũy kể từ thứ Ba tuần trước.
Tôi đã từng ở cả hai trường phái. Trường phái đầu tiên thì chậm hơn vào ngày đầu tiên nhưng nhanh hơn vào ngày thứ chín mươi. Trường phái thứ hai thì ngược lại. Và cho đến khoảng một tháng trước, công cụ thiết kế API mà tôi sử dụng nhiều nhất — Apidog — chỉ thực sự phục vụ trường phái thứ hai. Trình thiết kế trực quan của nó rất xuất sắc. Tính năng YAML round-trip của nó là một tính năng bạn phải bảo vệ trong quá trình đánh giá mã.
Sau đó vào giữa tháng 4, Chế độ Ưu tiên Đặc tả (Beta) đã xuất hiện trong hộp thoại Tạo Dự án Mới. Tôi đã cố tình không viết về nó vào ngày ra mắt. Tôi muốn sử dụng nó cho một thứ gì đó thực tế trước, và tôi muốn chờ đủ lâu để những lỗi phát sinh trong tuần đầu có cơ hội lộ diện. Một tháng là khoảng thời gian phù hợp. Bài viết này là những gì tôi tìm thấy sau khi dành một buổi sáng thử nghiệm phiên bản beta này với một đặc tả OpenAPI từ một trong các dự án phụ của tôi — những gì tôi sẽ nói với đồng đội trước khi họ dùng thử, và nó phù hợp hay không phù hợp ở đâu.
Chế độ Ưu tiên Đặc tả thực sự thay đổi điều gì
Tóm lại: Apidog hiện có hai chế độ dự án, và chúng thực sự là những sản phẩm khác biệt bên trong.
Chế độ mặc định là những gì hầu hết mọi người đều biết. Bạn nhấp vào + Tạo Dự án Mới, bạn sẽ có một cây thư mục và các biểu mẫu trực quan, và bạn xây dựng các endpoint bằng cách điền vào các trường. Đặc tả OpenAPI được tạo ra ngầm. Nó hoạt động tốt, đặc biệt đối với các đội chưa có thói quen sử dụng YAML mạnh mẽ.
Chế độ Ưu tiên Đặc tả thay thế trình chỉnh sửa biểu mẫu bằng một trình soạn thảo mã thực sự trên các tệp .yaml và .json thô, cùng với tính năng đồng bộ hóa hai chiều với kho lưu trữ Git của bạn. Đặc tả OpenAPI của bạn là tệp trên đĩa, không phải là một chuỗi các cú nhấp chuột. Có tính năng đánh dấu cú pháp, tự động hoàn thành theo lược đồ OpenAPI, và một khung “Phân tích thư mục theo thời gian thực” (Real-time Directory Parsing) xây dựng một dàn ý endpoint ở thanh bên từ mã của bạn khi bạn gõ.
Chi tiết cuối cùng đó là điều tôi sẽ bắt đầu nếu tôi giới thiệu điều này cho một người hoài nghi. Lý do tồn tại của các trình thiết kế trực quan không phải vì YAML khó — mà vì YAML che giấu cấu trúc cho đến khi bạn đã cuộn qua nó. Chế độ xem dàn ý của Apidog giải quyết vấn đề đó mà không buộc bạn phải từ bỏ tệp. Bạn viết đặc tả, bạn có điều hướng. Cả hai cùng tồn tại trên màn hình.
Luận điểm, nếu có: phát triển ưu tiên đặc tả chưa bao giờ là về việc ưu tiên các trình soạn thảo văn bản. Đó là về việc ai sở hữu sản phẩm. Chế độ Ưu tiên Đặc tả biến sản phẩm thành tệp trong kho lưu trữ của bạn, chấm hết. Giao diện người dùng là một cửa sổ nhìn vào nó, không phải là một lớp bao bọc xung quanh nó.
Thiết lập, từ đầu đến cuối
Đây là con đường tôi đã đi. Mất chưa đầy mười phút, phần lớn là ủy quyền Git.
1. Tạo dự án ở chế độ phù hợp. Từ màn hình dự án, + Dự án Mới → Chung → Chế độ Ưu tiên Đặc tả. Trình chọn chế độ dễ bị bỏ qua nếu bạn đã tạo dự án tự động trong một năm — Chế độ Chung được gắn cờ “Đề xuất” và mắt bạn sẽ lướt qua ô thứ hai. Hãy chậm lại ở đây.
2. Kết nối với kho lưu trữ Git của bạn. Cuộn đến Kết nối với Kho lưu trữ Git và ủy quyền nhà cung cấp của bạn. Tôi đã sử dụng GitHub; tài liệu sẽ đề cập đến các nhà cung cấp khác. Sau đó chọn Tổ chức, Kho lưu trữ, và nhánh Chính. Apidog sẽ đồng bộ hóa các tệp đặc tả trong nhánh đó làm bản sao làm việc của bạn.
3. Cấu hình dự án. Nhập Tên dự án, đặt quyền của nhóm, và Tạo. Lần đồng bộ hóa đầu tiên sẽ kéo bất kỳ tệp .yaml và .json nào có trong kho lưu trữ vào không gian làm việc của Apidog.
4. Chỉnh sửa đặc tả như một tệp, không phải một biểu mẫu. Mở một trong các tệp YAML. Bạn sẽ có một trình chỉnh sửa thực sự, tự động hoàn thành nhận biết lược đồ, và dàn ý endpoint xuất hiện ở thanh bên khi bạn gõ. Nếu bạn đã dành thời gian sử dụng VS Code với tiện ích mở rộng OpenAPI, điều này sẽ quen thuộc — ngoại trừ dàn ý được kết nối với điều hướng, và nhấp vào một endpoint sẽ nhảy đến dòng chính xác.
5. Commit và push. Góc trên bên phải, Commit & Push. Hộp thoại mở ra một phần Changes liệt kê các tệp đã sửa đổi, một trường Commit Message, và hai nút: Push hoặc Discard all changes. Không có bước dàn xếp riêng biệt — bất cứ thứ gì trong Changes đều sẽ được commit. Đó là một sự đơn giản hóa có chủ đích, và đối với hầu hết các quy trình chỉnh sửa đặc tả thì đó là một lựa chọn đúng đắn.
6. Theo dõi chỉ báo đồng bộ hóa. Góc dưới bên trái — bạn có thể thấy nó là Synced just now trong Hình 1. Nó cho bạn biết liệu các chỉnh sửa cục bộ của bạn đã được push, pull, hay không đồng bộ với remote. Tôi để nó mở ở một góc màn hình và nó trở thành thứ tôi tin tưởng hơn các hộp thoại modal. Nếu chỉ báo màu xanh lá cây, bạn và kho lưu trữ đồng ý.
Đó là toàn bộ bề mặt. Sáu bước, không cần cấu hình công cụ đồng bộ hóa riêng biệt, không cần cài đặt plugin.
Những điều tôi nhận thấy mà tài liệu không nói
Ba điều đáng lưu ý, tất cả đều từ một buổi sáng mày mò với nó.
Chế độ xem dàn ý cập nhật nhanh hơn tôi mong đợi. Tôi đã sử dụng nhiều “trình chỉnh sửa OpenAPI trực tiếp” trước đây và hầu hết chúng phân tích lại khi lưu, điều đó có nghĩa là có độ trễ 30 giây giữa việc thêm một endpoint và nhìn thấy nó ở thanh bên. Dàn ý của Apidog cập nhật khi tôi gõ — đủ gần như tức thì khiến tôi ngừng kiểm tra. Nghe có vẻ là một điều nhỏ nhặt. Không phải vậy. Đó là sự khác biệt giữa việc tin tưởng dàn ý như một công cụ điều hướng so với việc kiểm tra nó như một báo cáo trạng thái.
Tích hợp Git thực sự là hai chiều. Tôi đã chỉnh sửa cùng một tệp trong bản sao cục bộ của mình và push từ terminal khi Apidog đang mở. Apidog nhận ra, chỉ báo đồng bộ hóa chuyển sang “phía sau,” và một cú nhấp chuột đã kéo các thay đổi vào trình chỉnh sửa mà không cần hộp thoại hợp nhất. Tính năng đồng bộ hóa hai chiều mà tài liệu hứa hẹn là trải nghiệm thực tế, không phải là một tóm tắt tiếp thị. Nếu bạn có một đồng đội từ chối sử dụng bất cứ thứ gì ngoài Vim, họ có thể tiếp tục sử dụng Vim, và bạn có thể tiếp tục sử dụng Apidog, và tệp trong kho lưu trữ vẫn là một thứ duy nhất mà cả hai bạn đang chỉnh sửa.
Không có lối thoát để quay lại trình thiết kế trực quan trong cùng một dự án. Điều này là có chủ đích, nhưng đáng để biết trước khi bạn cam kết. Nếu bạn chọn Chế độ Ưu tiên Đặc tả khi tạo, dự án đó là ưu tiên đặc tả. Bạn không thể chuyển đổi một dự án giữa chừng vì các mô hình dữ liệu bên dưới khác nhau. Đối với một nhóm muốn cả hai chế độ trên cùng một đặc tả, quy trình làm việc là: giữ đặc tả trong một kho lưu trữ, trỏ một dự án Ưu tiên Đặc tả vào đó, và để người dùng chế độ trực quan mở một dự án riêng biệt nhập từ cùng một nguồn. Không liền mạch, nhưng có thể hoạt động.
Nơi nó phù hợp, và nơi nó không phù hợp
Tôi sẽ sử dụng điều này trong sản xuất. Đó là câu trả lời trực tiếp nhất tôi có thể đưa ra. Sự kết hợp giữa một trình chỉnh sửa thực sự, tính năng tự động hoàn thành tôn trọng lược đồ OpenAPI, và một chỉ báo đồng bộ hóa mà tôi có thể tin tưởng là điều tôi đã mong muốn từ Apidog trong hai năm.
Nhưng đây là phiên bản chân thực về đối tượng mà nó dành cho.
Nó phù hợp nếu bạn đã tự viết OpenAPI bằng tay, hoặc muốn vậy. Nó phù hợp nếu CI của bạn chạy spectral lint hoặc tạo SDK client từ đặc tả và đặc tả cần phải nằm trong Git. Nó phù hợp nếu bạn có một kỹ sư trong nhóm, người nếu không có nó sẽ mở các yêu cầu pull đối với tệp YAML từ VS Code, và bạn muốn mọi người hội tụ vào một công cụ mà không buộc họ phải rời khỏi bàn phím. Và nó đặc biệt phù hợp nếu bạn đang quản lý sự sai lệch giữa “đặc tả trong Apidog” và “đặc tả trong kho lưu trữ” bằng một bước make export mà không ai tin tưởng.
Nó không phù hợp nếu nhóm của bạn chưa bao giờ tiếp xúc với OpenAPI và trình thiết kế trực quan là lý do họ có thể đóng góp. Đối với những nhóm đó, chế độ mặc định vẫn là lựa chọn đúng đắn. Chế độ Ưu tiên Đặc tả đánh đổi sự dễ dàng trong việc làm quen để lấy độ chính xác, và sự đánh đổi đó là sai khi hầu hết những người đóng góp của bạn không phải là chuyên gia API.
Nó cũng chưa phù hợp, đối với các nhóm cần kết hợp cả hai chế độ trên cùng một dự án. Phiên bản beta thực sự là một bản beta ở khía cạnh đó. Tôi hy vọng điều này sẽ được cải thiện trong vài bản phát hành tiếp theo.
Điều rút ra
Phát triển ưu tiên đặc tả từng có nghĩa là bỏ qua các công cụ thiết kế API. Bạn hoặc sống với YAML và từ bỏ các trình chạy thử nghiệm và máy chủ giả lập, hoặc bạn sống với trình thiết kế trực quan và từ bỏ Git làm nguồn chân lý duy nhất. Động thái thú vị trong Chế độ Ưu tiên Đặc tả là Apidog đã ngừng yêu cầu bạn phải lựa chọn.
Tệp trong kho lưu trữ của bạn là tệp trong trình chỉnh sửa. Dàn ý là một chế độ xem, không phải một trạng thái. Đồng bộ hóa Git là sợi dây kết nối, không phải một tính năng. Nếu bạn đã chờ đợi một nền tảng API coi trọng việc ưu tiên đặc tả thay vì coi nó như một tùy chọn xuất, thì đây là nền tảng tôi khuyên bạn nên thử.
Phiên bản beta hiện đã có trong hộp thoại Tạo Dự án Mới. Tải xuống Apidog, chọn Chế độ Ưu tiên Đặc tả khi tạo, và trỏ nó vào một kho lưu trữ mà bạn đã tin tưởng. Lần commit đầu tiên mất mười phút. Quyết định có nên giữ nó hay không mất khoảng một tuần.
button