# Add OpenAPI Docs to a Fiber App

Yes. An agent annotates your Fiber v3 handlers for swag, generates the OpenAPI spec, mounts Swagger UI from gofiber/contrib, guards the spec in CI, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-openapi-docs/fiber/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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.

## More Fiber jobs

- [Add Prometheus Metrics to a Fiber App](https://getrush.ai/run/add-prometheus-metrics/fiber/)
- [Add Rate Limiting to a Fiber Login Endpoint](https://getrush.ai/run/add-rate-limiting/fiber/)
- [Add Request ID Logging to a Fiber App](https://getrush.ai/run/add-request-id-logging/fiber/)

## The same job on other stacks

- [Add OpenAPI Docs to a Flask API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/flask/)
- [Add OpenAPI Docs to a Gin API](https://getrush.ai/run/add-openapi-docs/gin/)
- [Add OpenAPI Docs to a Hono API](https://getrush.ai/run/add-openapi-docs/hono/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
