> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infraudit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# InfraAudit OpenAPI spec — download and usage

> Where to find the auto-generated OpenAPI 3.0 spec, how to download it, and how to use it with Postman, Swagger UI, or code generators.

The InfraAudit Go backend auto-generates an OpenAPI 3.0 specification from handler annotations using [swaggo/swag](https://github.com/swaggo/swag). You can explore the spec interactively in the browser or import it into your preferred tooling.

## View the spec in Swagger UI

When your InfraAudit server is running, open the interactive explorer in your browser:

```
http://localhost:8080/swagger/index.html
```

For SaaS, the Swagger UI is available at the same path on the API domain.

## Download the raw spec

Download the OpenAPI JSON spec directly from the running server:

```bash theme={null}
curl http://localhost:8080/swagger/doc.json > openapi.json
```

The generated spec file is also committed to source control at `docs/swagger.json` in the backend repository ([pratik-mahalle/infraudit-go](https://github.com/pratik-mahalle/infraudit-go)).

## Use with external tools

| Tool                  | How to use                                                             |
| --------------------- | ---------------------------------------------------------------------- |
| **Postman**           | File → Import → select `swagger.json`                                  |
| **Swagger Editor**    | Paste the contents into [editor.swagger.io](https://editor.swagger.io) |
| **OpenAPI Generator** | `openapi-generator generate -i swagger.json -g python -o ./client`     |
| **Stoplight**         | Import `swagger.json` or `swagger.yaml` from the file picker           |

## Regenerate the spec

If you're running a self-hosted deployment and have made changes to handler annotations, regenerate the spec:

```bash theme={null}
make swagger
# or
swag init -g cmd/api/main.go -o docs --parseDependency --parseInternal
```

The generated files in `docs/` are committed to source control and validated in CI.

## Handler annotation format

Each Go handler includes swag annotations that the tool uses to generate the spec. Example:

```go theme={null}
// List returns all drifts
// @Summary List drifts
// @Description Get paginated drift detections
// @Tags Drifts
// @Produce json
// @Param severity query string false "Filter by severity"
// @Success 200 {object} utils.PaginatedResponse{data=[]dto.DriftDTO}
// @Failure 401 {object} utils.ErrorResponse
// @Security BearerAuth
// @Router /api/v1/drifts [get]
func (h *DriftHandler) List(w http.ResponseWriter, r *http.Request) {
```

See the backend repo's `docs/README.md` for the full annotation reference.