Ask HN: How do you document a REST API?

[fifthofhisname]

Be it a work, side project or personal REST API - how do you document it for the public to consume?

How do you manage multiple documentation pages if parts are separated (e.g. public vs. internal) or paywalled (e.g. free, paid, premium)?

[Jemaclus]

I typically start with OAS or Swagger[1] and define the API spec in YAML or JSON and then generate documentation based on that. There are a bajillion Swagger doc generators that can make things really pretty, such as Spectacle[2], which I've used in the past.

I wouldn't try to roll your own, unless you want to pursue that as an educational exercise.

As far as splitting it up for public vs internal, I'd just have two separate repositories for the data. You should ideally be dogfooding your own APIs, so most of your APIs should be in the public area. If you namespace your APIs appropriately, you could have Nginx or Apache rules to block public access to certain URLs, such as /internal.

[1] https://swagger.io/specification/ [2] https://github.com/sourcey/spectacle