Bạn làm cách nào để ghi lại một API REST?

Question

Bạn làm cách nào để ghi lại API REST? Không chỉ là tài liệu về nguồn lực, nhưng thực sự dữ liệu được gửi trong yêu cầu là gì và dữ liệu nào được gửi lại trong phản hồi. Nó không đủ hữu ích để biết rằng một cái gì đó hy vọng XML được gửi và trả về XML; hoặc JASN; hay bất cứ cái gì. Làm cách nào để bạn ghi lại dữ liệu được gửi trong yêu cầu và dữ liệu được gửi lại trong phản hồi?

Tốt nhất tôi có thể tìm thấy cho đến nay là công cụ Enunciate nơi bạn có thể ghi lại REST API của bạn và các phần tử dữ liệu. Là Enunciate đúng loại công cụ này và tôi bỏ lỡ bất kỳ công cụ khác mà cung cấp này mà tôi nên xem xét?

tiêu dùng của API REST của tôi có thể ở bất kỳ ngôn ngữ python, Java, .NET, vv

Answer 1

Phương pháp mà tôi đã quyết định chọn cho dự án của tôi là phát âm. Dường như là tiêu chuẩn thực tế cho tài liệu REST API.

Answer 2

Tôi không chắc chắn nếu bạn đang yêu cầu một công cụ hỗ trợ bạn trong việc này, hoặc nếu bạn đang yêu cầu thực hành tốt nhất là gì (hoặc cả hai). Theo các thực hành tốt nhất, những điều tương tự áp dụng cho tài liệu REST như tài liệu phần mềm khác - cung cấp trang đích tốt với bề rộng (ví dụ: danh sách tài nguyên của bạn được sắp xếp hợp lý với sự lo lắng về những gì họ làm và URI của họ) với các trang chi tiết giải thích sâu về những gì mỗi người làm, với các ví dụ. API REST của Twitter được viết rất tốt và nó phải là một mô hình tốt.

Twitter API main page

Sample drilldown of one resource

Tôi thực sự yêu rằng trang Drilldown. Nó liệt kê tất cả các thông số bạn cần, với mô tả của từng thông số. Nó có một thanh bên liệt kê các loại được hỗ trợ. Nó có liên kết đến các trang liên quan và các trang khác có cùng một thẻ. Nó có một yêu cầu và đáp ứng mẫu.

Answer 3

Tôi có thể sai, nhưng có vẻ như bạn muốn một cái gì đó tương tự như WSDL và Lược đồ XML để ghi lại API của bạn. Tôi khuyên bạn nên đọc bài viết của Joe Gregorio trên Do we need WADL? Nó có một cuộc thảo luận tốt về lý do tại sao không sử dụng phương pháp này cho một API REST. Nếu bạn không muốn đọc toàn bộ bài viết, ý tưởng cơ bản là tài liệu giống như API (tức là WADL) sẽ không bao giờ đủ và sẽ dẫn đến các giao diện giòn. Một bài viết hay khác là Does REST need a description language? Nó có rất nhiều liên kết tốt cho loại thảo luận này.

Trong khi bài đăng của anh ấy cung cấp cho bạn lời khuyên về những việc không nên làm, nó không thực sự trả lời câu hỏi về những gì bạn nên làm. Điều quan trọng nhất về REST là ý tưởng về một giao diện thống nhất. Nói cách khác, GET, PUT, POST và DELETE nên làm chính xác những gì bạn nghĩ rằng họ nên làm. GET truy xuất một đại diện của tài nguyên, cập nhật PUT, POST tạo và xóa DELETE.

Câu hỏi lớn sau đó là mô tả dữ liệu của bạn và ý nghĩa của dữ liệu. Bạn luôn có thể đi đường định nghĩa một Lược đồ XML hoặc một cái gì đó tương tự và tạo ra tài liệu từ lược đồ. Cá nhân, tôi không tìm thấy tài liệu được tạo bằng máy, tất cả đều hữu ích.

Theo quan điểm khiêm tốn của tôi, các định dạng dữ liệu tốt nhất có tài liệu mở rộng, có thể đọc được bằng con người với các ví dụ. Đây là cách duy nhất tôi biết cách mô tả đúng ngữ nghĩa. Tôi thích sử dụng Sphinx để tạo loại tài liệu này.

Answer 4

Tôi đã sử dụng Enunciate, điều này thật tuyệt vời nhưng tôi thực sự không thích các khách hàng mà bạn có thể tạo ra với nó. Mặt khác, tôi đã sử dụng swagger trên các dự án cuối cùng của mình và dường như nó phù hợp với nhu cầu của tôi, nó thực sự tuyệt vời, bạn nên thử!

CẬP NHẬT 03/08/2016: Có vẻ như bạn có thể sử dụng Enunciate để tạo tài liệu swagger.
Xem this.