6 ms·
Ask HN: What tools do you use for Developer Portals / API Docs?
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?
- midgetjones 9y agoI don't have experience in either of the options you found, but readme.io is pretty good in my experience.
- pplonski86 9y agoI'd recommend Slate https://github.com/lord/slate https://github.com/lord/slate
- keviv 9y agoSwagger 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/
- mtmail 9y agoI 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.
- sedzia 9y agovery satisfied with https://readme.io https://readme.io
- teddyqwerty 9y agohttps://readme.io https://readme.io is the very best!
- michaelsobota 9y agoGreat, 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.
- scalesolved 9y agoI'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.
- wing328hk 9y agoIf 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