Slate vs Swagger - Cái nào tốt hơn và có nhiều lựa chọn hơn?

Question

Tôi phải ghi lại tài liệu API của mình. Tôi phải sử dụng bất kỳ một trong số họ Slate Hoặc Swagger. Tôi muốn biết cái nào có nhiều lựa chọn, ưu và nhược điểm hơn, cái nào tốt hơn.

Answer 1

Swagger and Slate phục vụ hai mục đích khác nhau. Swagger là một nỗ lực theo cách chuẩn hóa mô tả API RESTful (tương tự, ví dụ: ApiBlueprint)

Swagger là định dạng định nghĩa API dựa trên JSON, cho phép mô tả các API REST.

~ API Design Tooling From Swagger

Slate, mặt khác là một chủ đề khá cho các văn bản tài liệu API tốt đẹp.

1. Hai là không loại trừ lẫn nhau
2. Lý tưởng nhất, ta nên tạo ra tài liệu đá phiến của bạn từ Swagger bạn mô tả API

Mục tiêu của Swagger là cung cấp một tiêu chuẩn khi mà những người khác có thể xây dựng công cụ mở rộng (ví dụ: tài liệu, trình khám phá API, máy chủ giả, tạo mã, tiện ích thử nghiệm, v.v.). Xem, ví dụ: Swagger Tooling

Nhiều câu hỏi của bạn: Một số dụng cụ Slate cho vênh vang:

• Đây là một link to a Slate themed swagger UI
• Đây là một dự án mà generates Slate docs based on your Swagger definition

Vì vậy, hai là không loại trừ lẫn nhau, nhưng đối với câu hỏi trực tiếp của bạn: Thực hiện Swagger sẽ cung cấp cho bạn nhiều tùy chọn hơn và linh hoạt hơn (cũng như khả năng tạo tài liệu Slate).

Answer 2

Từ quan điểm của tôi, những công cụ này có mục đích rất khác nhau. Swagger là ngôn ngữ mô tả, trong khi phương tiện chặn chỉ dành cho tài liệu.

Tôi đã sử dụng chuyển đổi để tạo mô tả, từ đó tôi có thể tự động tạo các ứng dụng khách khác nhau cho API của mình, thậm chí cả tài liệu tự tạo.

Bạn cũng có thể tạo Markdown từ thông số dao động và sử dụng các đánh dấu đó trong Slate. [1]

[1] https://github.com/RobWin/swagger2markup

Answer 3

Về Slate:
- API Tài liệu bản mẫu/Khung
- có vẻ tốt
- dễ sử dụng
- Cú pháp tô sáng
- Ngôn ngữ cụ thể - Tabbed
- Tìm kiếm trang
- Bố cục tùy chỉnh 3 cột
- Chúng tôi có thể tạo bảng
- liên kết cuộn để mỗi khối/phương pháp/tiêu đề
- Thông báo sở [3 loại] - cảnh báo, thành công, thông báo
- Bàn mã lỗi http
- cú pháp Markdown
- Chúng ta có thể sử dụng trang web Logo
- Demo

Về Swagger:
- Nó cung cấp cho chúng ta truy cập API bên trong các tài liệu chính nó, nơi chúng tôi có thể kiểm tra phản ứng đối với bất kỳ yêu cầu cụ thể.
- Nó cung cấp một hình ảnh rõ ràng về API phản hồi với các thông số và tùy chọn của chúng. - YAML dựa dạng
- Không phù hợp cho hypermedia API
- Không có dụng cụ thiết kế cho Swagger
- Responses là trong XML hoặc JSON
- Swagger JS - thư viện JavaScript để kết nối với các API vênh vang cho phép thông qua trình duyệt hoặc nodejs
- Swagger Node express - mô-đun Swagger cho Node.js nhanh mô-đun
- Nó có vênh vang UI framework
- Demo

Answer 4

tôi làm cho đá phiến-bình (https://github.com/AhnSeongHyun/slate-flask) dựa trên python-bình.

các tính năng:

• Cấu hình File (config.json): Đặt tiêu đề, ngôn ngữ lập trình cho mã ví dụ sử dụng config.json dựa trên JSON Format. Cũng thiết lập đường dẫn của các tài liệu API và TOC (Mục lục).

• Hỗ trợ tài liệu đa API: Bản gốc hỗ trợ một tài liệu API dựa trên định dạng Markdown.Nhưng slate-flask hỗ trợ nhiều tài liệu API để quản lý hiệu quả và lượng tài liệu sử dụng TOC (index.json).

• Hỗ trợ thay đổi động của tài liệu: Bạn có thể phản ánh các thay đổi của tài liệu API mà không cần khởi động lại máy chủ. Khi làm mới trang web, nếu có thay đổi, hãy tải lại tài liệu API của slate-flask. Người dùng chỉ tập trung vào việc viết tài liệu API.