JSONAPI-Resources / JSONAPI-Resources/jsonapi-resources
API Documentation generation
Chưa có ai nhận issue này.
- Ngôn ngữ chính
- Ruby
- Star
- 2.3k
- Fork
- 546
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
Hey there,
We need to generate a documentation for our new API written with jsonapi-resources (oh yeah!), authenticated with doorkeeper (OAuth2) and versioned with versionist (HTTP Header).
I have reviewed some tools (api-blueprint, apipie, swagger, slate, ...) and would like to know what's your position on them. Do you already have a preference?
It seems obvious there's already a lot of logic encapsulated inside our API resources/routes files and that we should be able to generate some documentation automagically instead of rewriting everything manually to some markdown/yaml/... files.
Do you think starting something like grape-apiary make sense? Is it too early, maybe not enough stable API yet?
Let start the discussion!
/cc @barelyknown & @dgeb If I remember well, you discuss this on a the Ruby on Rails Podcast 187
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Hướng nghiên cứu
Xem xét các tệp tài nguyên/route API hiện có và các yêu cầu từ jsonapi-resources, doorkeeper và versionist. So sánh các công cụ được đề cập, bao gồm api-blueprint, apipie, Swagger, Slate và grape-apiary. Được xem là hoàn tất khi thống nhất được cách tiếp cận tạo tài liệu và phạm vi của nó; issue không nêu tên các tệp hoặc test cụ thể.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- ruby
- Lĩnh vực
- api, documentation
- Loại issue
- Tài liệu
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Cần làm rõ
- Mức phù hợp với người mới
- 25/100