What the agent does
The agent starts from the routes, because an OpenAPI document that does not match the handlers is worse than none. In a Fiber app laid out like gofiber/boilerplate, app.go builds the app inside main: recover and logger middleware, a /api/v1 group with GET /users bound to handlers.UserList and POST /users to handlers.UserCreate, then app.Get("/*", static.New("./static/public")) as a catch-all and handlers.NotFound as the final handler. go.mod is on github.com/gofiber/fiber/v3 v3.6.1 with Go 1.26.0, there is no docs package, there is no test file, and handlers/handlers.go answers with fiber.Map literals ({"success": true, "users": [...]}) rather than named types, which matters because swag documents a response by its Go type.
It then writes the annotations. A general block above main in app.go carries @title, @version, @description, @BasePath /api/v1 and @host, and each handler gets @Summary, @Tags, @Accept, @Produce, @Param and @Success lines: UserCreate reads c.FormValue("user"), so its parameter is user formData string true, and models.User has the one Name field with a json:"name" tag. Because fiber.Map has no shape swag can read, the agent adds UserListResponse and UserCreateResponse structs in handlers with Success bool and the user fields, returns those from the handlers, and references them in @Success 200 {object}. The generator is github.com/swaggo/swag/cmd/swag on its v1.16 line (the v2 tags are still release candidates), run as swag init -g app.go -o docs, which writes docs/docs.go, docs/swagger.json and docs/swagger.yaml; the Go file carries a Code generated header, so golangci-lint v2.14.0 from lint.yml skips it.
Serving the UI is one route and one import. The agent adds github.com/gofiber/contrib/v3/swaggo, whose own go.mod requires the same Fiber v3.6.1, imports the generated docs package for its side effect (_ "boilerplate/docs"), and registers app.Get("/swagger/*", swaggo.HandlerDefault) above the static catch-all, since Fiber matches routes in registration order and /* would otherwise swallow it. The default config serves the UI at /swagger/index.html and the document at /swagger/doc.json. To make the app testable it moves construction out of main into newApp() *fiber.App, and writes app_test.go that calls app.Test with a request for /swagger/doc.json, decodes the JSON and asserts the /users path is present with both methods, so go test ./... -v -race in test.yml has something to run on both matrix Go versions.
Last, it keeps the spec from drifting: a docs target in the Makefile beside run-local and requirements, and a step in test.yml that runs the same swag init and fails on git diff --exit-code docs, so a handler annotated differently from its generated file cannot merge. The Dockerfile already copies the whole module before go build, so the docs package ships in the image without a change.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add OpenAPI docs to this Fiber v3 app. Read go.mod, app.go, handlers/handlers.go, models/user.go, database/database.go, Makefile, Dockerfile, .golangci.yml and .github/workflows/test.yml first. Add swag general annotations above main and handler annotations on UserList and UserCreate, replacing the fiber.Map responses with named response structs so swag can document them. Generate the spec with the swag CLI on its v1.16 line into docs/, add github.com/gofiber/contrib/v3/swaggo and mount it on /swagger/* before the static catch-all route. Move app construction into a newApp function and write a test that fetches /swagger/doc.json and checks the /users path. Add a Makefile target that regenerates docs and a CI step that fails when the generated files are out of date. Run go vet, go test ./... -race and golangci-lint, and open a pull request with the output. Do not change the existing handlers' behaviour.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request touches app.go, handlers/handlers.go, go.mod, go.sum, the Makefile and .github/workflows/test.yml, and adds the three files under docs/ plus app_test.go. Its description shows the route list the spec documents, the swag init command it ran, and the go vet, go test and golangci-lint output from the sandbox.
Test and Linter run on the pull request as before; Test now has a test to execute and a drift step to pass. Opening /swagger/index.html on a running build shows the two users operations with the form parameter and the named response bodies.
A reviewer checks three things before merging: that the response structs carry the same field names the fiber.Map literals did, so no client sees a changed body; that the @host value is right for where the app is deployed, or is left empty so Swagger UI uses the current origin; and whether the documentation route should sit behind the same controls as the API in production.
Run it on every Go service without API docs
A team that stamps services from this boilerplate runs this once per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads its own app.go and groups, so a service with /api/v2 gets that @BasePath, and one that already returns named structs gets annotations only.
To keep later handlers documented, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds or changes a route in app.go or handlers/, check that its swag annotations and the generated docs/ match, and comment with what is missing" reviews each change. The trigger adds the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The hard part of this job is not the annotations, it is checking them: running the generator at a version the module can build with, seeing that the Swagger UI route survives the static catch-all, and confirming the document describes the body the handler actually returns. The agent does that in its own sandbox against the module's pinned Fiber version, with the generated files and the test output kept with the run.
Because the sandbox has Go and the module's dependencies, the same go test -race and golangci-lint that test.yml and lint.yml run happen before the pull request opens, and their output is quoted in it. For a team with several Fiber services, each repository gets its own run and its own pull request, fitted to its routes.
Frequently asked questions
Does this work with Fiber v3, or only v2?
It is written for v3. The archived github.com/gofiber/swagger module says to use github.com/gofiber/contrib/v3/swaggo instead, and that module's go.mod requires Fiber v3.6.1, the version this boilerplate is on. A v2 app would use the older github.com/gofiber/swagger module with the same swag annotations; the agent reads go.mod and picks accordingly.
Why change the handlers at all?
swag builds response schemas from Go types, and fiber.Map is a map of any, which documents as an empty object. Named structs with the same JSON tags produce the same bytes on the wire and give the spec real fields. The test compares the documented path list against the routes, and the handlers' behaviour is unchanged.
Which swag version does it use?
The v1.16 line, installed with go install github.com/swaggo/swag/cmd/swag@v1.16.6 in the sandbox and in CI. The v2 tags are release candidates with a different output layout. Because go.mod is on Go 1.26, the agent can also record the generator with go get -tool so go tool swag runs the pinned version for everyone.
Will the generated docs/ files cause lint failures?
No. swag init writes docs/docs.go with a Code generated ... DO NOT EDIT header, and golangci-lint skips generated files by default. The lint.yml workflow also passes --tests=false, so the new app_test.go is not linted either.
Should Swagger UI be exposed in production?
That is the reviewer's call, and the pull request says so. The route is registered unconditionally so it can be tested; a one-line change gates it behind the -prod flag the app already parses, or behind whatever auth middleware the API gets later.