Trình tạo tài liệu JSON API RESTful

Question

Tôi tự hỏi liệu có ai có bất kỳ kinh nghiệm hoặc kiến ​​nghị nào về các công cụ có thể được sử dụng để tạo các trang web có tài liệu và cho phép bạn chơi với API JSON RESTful hay không. Tôi đang nghĩ về một cái gì đó giống như Github Developer API hoặc Google API Console.

Nhìn xung quanh, tôi đã tìm thấy swagger từ Wordnik, có vẻ tốt. Nhưng tôi tự hỏi nếu có bất cứ điều gì khác ngoài kia và trải nghiệm của mọi người là gì với những công cụ này. Cảm ơn bạn.

Answer 1

Có một số thứ khác như enunciate và I/O Docs.

Và đây là một blog về chủ đề này: Automated Documentation for REST APIs

Answer 2

Chúng tôi đang làm việc trên một sản phẩm gọi là http://apiengine.io để giải quyết vấn đề này

Answer 3

Tôi thích Apiary. Vẫn còn trong thông lượng, nhưng nhìn khá tốt.

Answer 4

Tôi vừa tạo một đá quý ruby ​​"calamum" để tạo một tài liệu api html còn lại, rất dễ sử dụng. https://github.com/malachheb/calamum.

Answer 5

Swagger có thể dành cho bạn. Nó có triển khai bằng nhiều ngôn ngữ khác nhau.

Answer 6

Chúng tôi đang làm việc trên MireDot hoạt động với Java/Jax-rs. Thiết lập ban đầu mất chưa đầy 5 phút. Một phiên bản cơ sở rất có khả năng là miễn phí.

Answer 7

Đề xuất của tôi sẽ không tin tưởng quá trình tạo tài liệu từ mã nguồn quá nhiều. Tôi nghĩ rằng khán giả của tài liệu cuối cùng là con người và họ cần nhiều hơn những gì các tệp WADL và máy tạo ra có thể cung cấp. Để hỗ trợ các công cụ bạn phải đầu tư thời gian và công sức để làm chủ các idosyncracies của một công cụ.

Ngoài ra, có một giới hạn thực tế về số lượng có thể được bao gồm bên trong mã nguồn của API. Chỉ cần ghi lại tên và loại tham số sẽ không giúp ích nhiều (và hoàn thành) và thêm yêu cầu mẫu và phản hồi bên trong mã nguồn trông có vẻ không ổn định (mặc dù thông tin cần thiết cho người dùng cuối). Một lý do khác có thể đơn giản là thẩm mỹ.

Twitter cũng duy trì tài liệu bằng tay và điều đó nói rất nhiều. IMHO, lựa chọn tốt nhất là duy trì tài liệu ở định dạng thân thiện với con người và tạo HTML/PDF, v.v.

Shameless Cắm

https://github.com/rjha/restdoc

Đây chỉ là vài script PHP rất đơn giản mà đọc API từ các tập tin định nghĩa YAML và tạo HTML. Có thể không mở rộng tốt cho loại API khổng lồ của eBay nhưng đối với các yêu cầu tài liệu API đơn giản, đây có thể là một cách để đi.

Answer 8

rest-tool là công cụ dòng lệnh đơn giản được viết bằng JavaScript sử dụng Node.js. Nó có thể tạo ra các dự án độc lập cung cấp tài liệu, mô phỏng và kiểm tra tự động các API RESTful.

Bạn có thể tạo API hoạt động sau vài phút đóng vai trò như DMZ giữa giao diện người dùng và người phụ trợ.

Nó tạo tài liệu, trường hợp kiểm tra và thậm chí cả logic mô phỏng động máy chủ dựa trên mẫu, vì vậy mọi thứ đều có thể tùy chỉnh cao.

Answer 9

Tôi vừa tạo Swadl, một trình tạo tài liệu WADL được lấy cảm hứng từ sóng chéo.

Về cơ bản, không có tích hợp nào cả - chỉ cần chuyển nó vào wadl của bạn và tạo trang.

Kiểm tra nó ra ở đây: https://github.com/ehearty/Swadl

Và xem một bản demo ở đây: http://ehearty.github.io/Swadl/wadl.html

Tôi rất muốn phản hồi về công cụ của tôi

Answer 10

câu hỏi là khá cũ nhưng tôi tin rằng vẫn còn thực tế. Tôi biết các công cụ thiết kế ba API:

• Swagger (không có giải pháp SaaS)
• RAML (apihub.com)
• API Blueprint (apiary.com) Tất cả đều được bao gồm trong bài đăng blog - http://apievangelist.com/2014/03/08/hello-world-product-api-with-blueprint-raml-and-swagger/
  tôi khuyên bạn nên đi theo anh chàng rằng nếu bạn đang quan tâm đến API

cá nhân tôi nghĩ rằng những công cụ này là tốt để chia sẻ tài liệu API giữa các thành viên các nhóm phát triển tương đối nhỏ, nơi mọi nhà phát triển đều biết về hầu hết các chi tiết cụ thể cho dự án cụ thể và họ chỉ cần biết liệu đó là POST hoặc PUT và tên của các trường JSON kết quả là gì.

Chúng tôi cần phải có các tính năng quản lý nội dung phong phú và thuận tiện cùng với các công cụ cụ thể REST có chức sẽ tạo ra các văn bản đẹp trong các định dạng khác nhau như html đơn trang hoặc pdf Chúng tôi không thể tìm thấy phần mềm khá để chúng tôi quyết định tạo ra Speca.io

Hiện tại, nó ở dạng alpha và hoàn toàn miễn phí nhưng chúng tôi rất hoan nghênh khi phát nội dung đó và mọi phản hồi sẽ được đánh giá cao.