go-api-docs

When to Use

• Documenting HTTP API endpoints
• Generating OpenAPI/Swagger specs
• Writing service README files
• Documenting gRPC services (protobuf is self-documenting)

Critical Patterns

Pattern	Rule
Swagger from annotations	Use swaggo/swag to generate OpenAPI from Go comments
Spec lives with service	Each service generates its own docs/swagger.json
Proto is self-documenting	gRPC services use protobuf comments as docs
README per service	Each service has a README with setup, architecture, API summary
Keep specs in sync	Regenerate on every API change — add to CI

Swagger Annotations (swaggo/swag)

See assets/swagger_main.go

See assets/swagger_handler.go

Serve Swagger UI

See assets/swagger_ui.go

Protobuf Documentation

Protobuf files are self-documenting. Use comments:

See assets/caregiver.proto

Service README Template

See assets/README_TEMPLATE.md

Commands

# Install swag CLI
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs
swag init -g cmd/server/main.go -o docs

# Dependencies
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files
go get github.com/swaggo/swag

# View docs
open http://localhost:8080/swagger/index.html

# Makefile target
.PHONY: swagger
swagger:
	swag init -g cmd/server/main.go -o docs

Anti-Patterns

Don't	Do
Manually write OpenAPI YAML	Generate from code annotations
Swagger in production	Disable Swagger UI in production
Outdated README	Regenerate swagger on API changes, keep README current
No docs for events	Document published/consumed events in README
Undocumented protobuf	Add comments to every service, rpc, and message