JSONAPI-Resources / JSONAPI-Resources/jsonapi-resources
API Documentation generation
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 2.3k
- Forks
- 546
- PR merge metrics
- No merged PRs in 30d
Description
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
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing API resources/routes files and the requirements from jsonapi-resources, doorkeeper, and versionist. Compare the mentioned tools, including api-blueprint, apipie, Swagger, Slate, and grape-apiary. Done means agreeing on a documentation-generation approach and its scope; the issue does not name specific files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100