REST API Documentation Tools?

Ruby on Rails
1

I’m working on JSON API by using rails-api and have feature specs written in RSpec. I would like to build a documentation for each endpoints in my REST API, so my consumers(mobile developer, apps) they can know what endpoint already done and available, and also what request params or headers that need to be passed.

Do you know any available tools that can help? And what do you use to build your API documentation?

1 Like
2

I’ve used (and even contributed to) Weasel-Diesel in the past but these days I’d choose a JSON schema-based tool, so you don’t get locked into a single tool chain. This thread mentions different alternatives.

1 Like
3

Hi, @samnang; here are a few links I found that might help.

Rails API documentation guide: API Documentation Guidelines — Ruby on Rails Guides

Rails API document generator: rapi_doc | RubyGems.org | your community gem host

Another Rails API documentation generator gem: https://github.com/Pajk/apipie-rails

Use integration tests: Auto generate/maintain API documentation using Rails integration tests - RubyFlow

Hopefully some of that will be on target

2 Likes
4

I’ve seen documentation in Apiary that I thought was very nice.

2 Likes
5

Wow, these tools look great. I will check them out and choose the one that is easy to setup and doesn’t take a lot of effort to write it. Anyway I also found a few more:

https://github.com/zipmark/rspec_api_documentation
https://github.com/Pajk/apipie-rails

6

@samnang which tool did you end up using? Seems like there are lot of options.

7

@Nicolo I end up using GitHub - zipmark/rspec_api_documentation: Automatically generate API documentation from RSpec with GitHub - jejacks0n/apitome: Apitome: /iˈpitəmē/ An API documentation presentation layer for RSpec API Documentation output.