| name | update-api-reference |
| description | Regenerate the OpenAPI reference documentation after adding, modifying, or removing API endpoints in sandbox-api. Run this whenever handler signatures, route paths, or swag annotations change. |
Update the API Reference (OpenAPI Docs)
The OpenAPI spec is generated from swaggo annotations in the Go handler code. After changing any endpoint, regenerate the docs.
Run the Full Reference Update
make reference
This single command:
- Runs
swag init to parse Go annotations → generates sandbox-api/docs/swagger.yaml and docs.go
- Fixes type name references (replaces
filesystem.Directory with Directory)
- Converts Swagger 2.0 → OpenAPI 3.0 via
swagger2openapi
- Adds Bearer auth security scheme to all endpoints
- Runs
fixopenapi.sh for additional patches
The output file is sandbox-api/docs/openapi.yml.
How Swag Annotations Work
Annotations are Go comments above handler functions. Example:
func (h *FileSystemHandler) HandleGetFile(c *gin.Context) {
Key annotation fields:
@Summary — short description (shown in API reference)@Description — longer explanation@Tags — group endpoints in the UI (filesystem, process, network, codegen)@Param — parameter: name location type required "description"
- locations:
path, query, body, header
@Success / @Failure — response codes with type and description@Router — path and HTTP method [get|post|put|delete]@Accept / @Produce — request/response content types
Where the Docs Live
| File | Purpose |
|---|
sandbox-api/docs/openapi.yml | Final OpenAPI 3.0 spec (commit this) |
sandbox-api/docs/docs.go | Auto-generated Go embed of the spec |
sandbox-api/docs/fixopenapi.sh | Post-processing patches |
After Adding a New Endpoint
- Add swag annotations to your handler function
- Register the route in
sandbox-api/src/api/router.go
- Run
make reference
- Review the diff in
sandbox-api/docs/openapi.yml to confirm your endpoint appears correctly
- Commit both the handler changes and the updated
openapi.yml and docs.go
Verify the Generated Docs
Open the Swagger UI at http://localhost:8080/swagger/index.html while the dev server is running. It reads docs.go which is embedded at build time.
Troubleshooting
swag: command not found: Run make dependencies first- Missing endpoint in output: Check that your handler has a
@Router annotation and the function is exported
- Type not found: Ensure the struct is in the same package or imported and annotated with
@Description
swagger2openapi not found: Run npm install -g swagger2openapi or npx swagger2openapi (the Makefile uses npx)
