Tôi đang tìm cách tạo tài liệu cho API Rest của tôi đã được tạo bằng khung công tác Jersey.Tài liệu về phần còn lại của Jersey api
Có công cụ nào để tạo tài liệu như vậy không? Ngoài ra, các phương pháp hay nhất để ghi lại các API của Rest API là gì.
Tôi đã làm một ít nghiên cứu về điều này một vài tháng trước và kết luận của tôi là khuôn khổ đẹp nhất để ghi lại Jersey (và nhiều thứ khác!) REST API là "Swagger" - http://swagger.io/. Nó là một dự án mã nguồn mở (https://github.com/swagger-api/swagger-core) và rất đơn giản để sử dụng/tích hợp. Bạn chỉ cần thêm một số chú thích vào REST API của bạn và nó tạo ra một "trang web" với tất cả các tài nguyên API, các thông báo yêu cầu/phản hồi và thậm chí cho phép thực hiện kiểm tra trực tiếp từ đó. Dưới đây là ví dụ về tài liệu về tài nguyên API:
@POST
@Produces("application/json")
@Consumes({ "application/xml", "application/json"})
@ApiOperation(
value = "Short description of resources",
notes = "Detailed textual description of the resource...",
responseClass = "com.example.data.resps.PostExampleResp")
@ApiErrors(value = { @ApiError(code = 404, reason = "Resources Not Found"),
@ApiError(code = 400, reason = "Bad Request"),
@ApiError(code = 500, reason = "Internal Error")})
public PostExampleResp postExample(
@ApiParam(value = "Description of request message",
required = true) PostExampleReq request)
throws WebApplicationException{
...
Chú thích @Api... là chú thích Swagger. Bạn có thể thấy một bản demo trực tiếp của tài liệu API ở đây: http://swagger.io/swagger-ui/
Có một số dự án khác, cụ thể là:
Chúng tôi đang làm việc trên miredot. Nó sẽ làm việc out-of-the box mà không cần thêm (m) bất kỳ chú thích bổ sung nào. Bất kỳ thông tin phản hồi được chào đón.
Khoản thanh toán của nó .. Tôi không nghĩ rằng điều này sẽ hiệu quả đối với người đang tìm kiếm nguồn mở – CandleCoder
Tôi không chắc chắn cách tôi nên tích hợp với ứng dụng của tôi. Tôi đang sử dụng một máy chủ Tomcat với phần còn lại của api jersey - những gì tôi nên làm để tạo ra các tập tin tài liệu? –
Cách tốt nhất là làm theo hướng dẫn chính thức cho Java/JAX-RS (áo): https://github.com/wordnik/swagger-core/wiki/Java-JAXRS-Quickstart, nó rất tốt. Thực hiện theo nó vào dòng và bạn sẽ nhận được nó làm việc. Hãy nhớ rằng, nó sẽ không "tạo ra" tài liệu (như Javadocs) nó tạo ra các tài liệu "on the fly" dựa trên các chú thích trong mã của bạn (các dịch vụ web được triển khai). Trong dự án Github cũng có rất nhiều chi tiết/tài liệu/vấn đề-reponses có thể giúp đỡ. Hơn nữa, các nhà phát triển rất nhạy cảm về trợ giúp giải quyết bất kỳ vấn đề cụ thể nào. – emgsilva
Công cụ vênh vang hoạt động trên cơ sở rất xâm nhập: Nó nhấn vào dịch vụ web của bạn và nó cần chạy trong cùng một vùng chứa. Tôi đã cố gắng phân tách điều này bằng cách tạo ra JSON API-spec và chạy nó một cách riêng biệt trên một Swagger-UI, nhưng điều này là xa tầm thường và rất kém tài liệu. – Pepster