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?
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.
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.
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
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.