May 9, 2019

Best hosted api documentation tool?

ih11

I'm looking for a tool like gitbook.com to publish API docs. It has to be free or super cheap (<5$/mo) and support custom domain (docs.mysite.com).
Any tips?
I've tried Gitbook but found the editing is pretty clunky (e.g. can't reorder params in an API description, copy/pasting has issues, can't reorder pages, ...)

  1. 2

    We use https://swagger.io/ Swagger. It is very powerful but hard to get started on it

    1. 1

      Can you show me a sample documentation built with swagger?

  2. 1

    You could use an offline tool to generate the HTML, then host it somewhere free like Github Pages. There are a number of documentation generators out there, each one tends to be more popular with a specific language. E.g. Sphinx (http://www.sphinx-doc.org) for Python, mdBook (https://rust-lang-nursery.github.io/mdBook/) for Rust, etc. I quite like Pandoc (https://pandoc.org/epub.html) myself.

  3. 1

    Not specific to API docs, but GitBook is pretty slick for publishing docs kept in version control.

    1. 1

      Design looks great but it's pretty clunky when editing tbh.

  4. 1

    I'm looking to try out https://github.com/lord/slate

    It does require a server though. But you can easily set it up for free with a cheap machine on Google Cloud.

    I'd be interested to hear other options as well

    1. 3

      We run on Slate and host it on Github: https://api.supervisor.reviewshake.com/#introduction. Very simple deploys.

      1. 1

        Looks like exactly what i need. Can you tell me how your deployment process is like?

    2. 2

      Doesn't need to be on a server, it builds a static site. Used it for a previous project. Host on Netlify for free easy hosting as well.

      1. 1

        Thank you for clarifying !

    1. 1

      Thanks, but doesn't look like it's suited for API docs. It looks more like a more generic solution for general documents sharing.