
Ask HN: What tools do you use for Developer Portals / API Docs? - michaelsobota
What tools have you found useful to quickly build developer portals, specifically API documentation? We have looked at SwaggerHub and Gelato. Any feedback on either or other tools you have found to be valuable?
======
scalesolved
I've absolutely fallen in love with Spring Rest Docs
[https://projects.spring.io/spring-
restdocs/](https://projects.spring.io/spring-restdocs/) after a colleague
introduced me to it.

Essentially you write tests that then generate your documentation, so you get
a load of happy path integration tests and up to date documentation. It's a
great way to ensure the documentation and code does what it says.

Our happy path integration tests produce markdown files detailing the
route,payload, expected status codes etc and then we manually add these
snippets to a menu markdown file. When we work on a feature branch with public
API changes then our CI system detects documentation changes and when merged
pushes to Jekyll.

------
mtmail
I found gelato too complex when dealing with 2-5 methods only but I understand
that the tools are build for larger teams. It's great to get hosted
documentation up and running fast and code snippets for various languages to
get started.

Have a look at
[https://apiblueprint.org/tools.html](https://apiblueprint.org/tools.html)
which covers mocking APIs, converting to
[https://www.getpostman.com/](https://www.getpostman.com/), validation inside
IDEs and generating HTML for self-hosting.

[http://documentation.js.org/](http://documentation.js.org/) is relatively new
and seems to target nodejs primarily.

------
wing328hk
If you've a OpenAPI/Swagger spec, you can also use Swagger Codegen [1] (free &
open source) to generate API documentations. If you need help using the
generator, please open a a ticket via [https://github.com/swagger-api/swagger-
codegen/issues/new](https://github.com/swagger-api/swagger-codegen/issues/new)

[1] [https://github.com/swagger-api/swagger-
codegen](https://github.com/swagger-api/swagger-codegen)

------
keviv
Swagger is pretty great for API docs. I've used it in the past and there are
plenty of companies using it. [http://swagger.io/](http://swagger.io/)

------
pplonski86
I'd recommend Slate
[https://github.com/lord/slate](https://github.com/lord/slate)

------
sedzia
very satisfied with [https://readme.io](https://readme.io)

~~~
teddyqwerty
[https://readme.io](https://readme.io) is the very best!

~~~
michaelsobota
Great, thanks for the rec! Looks like they just got swagger support added in
which is important to us. We'll give the trial a go.

------
midgetjones
I don't have experience in either of the options you found, but readme.io is
pretty good in my experience.

