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 |
