I was building a new API recently, and was looking for a good documentation solution.
The commercial cloud based solutions (Gitlab, Confluence, et al) are pretty good, but you have to keep paying or your documentation disappears. Self hosted Wiki or documentation solutions were also out, due to the pain of migrating content in and out.
We ended up with a very simple solution of Markdown + CSS + Pandoc + make. Pandoc takes the CSS and MD files as input, and outputs HTML.
The MD files are in the API repository, deployment has been setup so that the latest documentation is deployed automatically with each API update.
I did have a look at swagger, but it felt way to bloated and complex for what we wanted. With Markdown we know that even in 10 years time when services like swagger are long gone, it'll be possible to view markdown files. Also, there is barely any learning curve with Markdown.
The commercial cloud based solutions (Gitlab, Confluence, et al) are pretty good, but you have to keep paying or your documentation disappears. Self hosted Wiki or documentation solutions were also out, due to the pain of migrating content in and out.
We ended up with a very simple solution of Markdown + CSS + Pandoc + make. Pandoc takes the CSS and MD files as input, and outputs HTML. The MD files are in the API repository, deployment has been setup so that the latest documentation is deployed automatically with each API update.