Ask HN: What tools do you use for Developer Portals / API Docs?

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

I'd recommend Slate https://github.com/lord/slate

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/

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 which covers mocking APIs, converting to https://www.getpostman.com/, validation inside IDEs and generating HTML for self-hosting.

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

very satisfied with https://readme.io

I've absolutely fallen in love with Spring Rest Docs 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.

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

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