How Do You Write an API Documentation

Open API Spec is a good starting place https://swagger.io/tools/swaggerhub/

When I am working on developing RESTful service, I choose to use go-doudou microservice framework. It has built-in OpenAPI 3.0 specification compatible online document. When your service has been deployed on server, frontend developers can visit the document from /go-doudou/doc page. The document is protected by http basic auth with default username/password admin/admin. Of cource you can configure them. The document supports rendering custom html+css code, means you can write plain text or html + css code behind // as golang comment above go interface declare place and methods, the comments will be rendering on online document.

BTW, the document ui is written by vuejs+typescript. It can be used standalone or integrated into your own framework by parsing OpenAPI 3.0 json format specification. I integrated it into my another java open source project, too.

go-doudou repo: https://github.com/unionj-cloud/go-doudou
document ui repo: https://github.com/unionj-cloud/go-doudou-openapi-ui

I use postman's documentation framework to share API documentation across teams: https://learning.postman.com/docs/publishing-your-api/documenting-your-api/

We document using OpenAPI, there are quite a few options out there. The only one I wouldn't use is the SwaggerUI version.

OpenAPI (previously swagger) or GraphQL is a must. Both support generating types (GraphQL supports generating even more helpers and has a query playground), so that errors in your code are easily detectable. Documentation is great too, but can often be integrated into and generated with OpenAPI or GraphQL too.