# Swag — Auto-Generate Go API Documentation from Annotations

> Swag converts Go annotations in source comments into Swagger/OpenAPI 2.0 documentation. It integrates with Gin, Echo, Fiber, and other Go web frameworks to produce interactive API docs automatically.

## Install

Save as a script file and run:

# Swag — Auto-Generate Go API Documentation from Annotations

## Quick Use
```bash
go install github.com/swaggo/swag/cmd/swag@latest
swag init
# serves Swagger UI at /swagger/index.html
```

## Introduction
Swag parses Go source code annotations written as structured comments and produces a complete Swagger 2.0 (OpenAPI) specification. Combined with middleware for Gin, Echo, Fiber, or Chi, it serves an interactive Swagger UI directly from your running Go application, keeping documentation in sync with the code.

## What Swag Does
- Parses Go comment annotations into a Swagger 2.0 JSON/YAML spec
- Generates interactive Swagger UI served by your Go application
- Supports request/response models, query params, headers, and auth definitions
- Handles nested structs, enums, arrays, and custom types automatically
- Validates annotations at generation time to catch errors early

## Architecture Overview
The `swag init` command walks the Go AST of your project, extracts specially formatted comments from handler functions, and builds an in-memory Swagger spec. It writes the spec as `docs/swagger.json` and a Go package that embeds the spec. At runtime, a framework-specific middleware (e.g., `gin-swagger`) serves the embedded spec through Swagger UI with no external file dependencies.

## Self-Hosting & Configuration
- Install the CLI with `go install github.com/swaggo/swag/cmd/swag@latest`
- Add annotations above handler functions following the Swag comment format
- Run `swag init` to regenerate docs after code changes
- Configure base path, host, and schemes via general API annotations in main.go
- Use `--parseDependency` to include models from external packages

## Key Features
- Zero-config generation from annotated Go comments
- Framework adapters for Gin, Echo, Fiber, Chi, and net/http
- Automatic model inference from Go struct tags
- Supports file upload, multipart form, and binary response types
- CI-friendly: run `swag init` in your build pipeline to keep docs current

## Comparison with Similar Tools
- **go-swagger** — full OpenAPI 2.0 toolkit but heavier; Swag focuses on annotation-driven generation
- **oapi-codegen** — generates Go code from an OpenAPI spec (spec-first); Swag is code-first
- **Swagger Editor** — manual spec editing; Swag derives the spec from source code
- **Redoc** — rendering-only; Swag handles both generation and serving
- **grpc-gateway** — targets gRPC services; Swag targets REST handlers

## FAQ
**Q: Does Swag support OpenAPI 3.0?**
A: Swag generates Swagger 2.0 specs. You can convert to OpenAPI 3.0 using tools like swagger2openapi.

**Q: How do I document authentication?**
A: Add `@SecurityDefinitions` annotations in main.go and reference them with `@Security` on each handler.

**Q: Can Swag parse models from other packages?**
A: Yes, use the `--parseDependency` flag to include structs defined in imported packages.

**Q: Does it work with Go modules?**
A: Yes, Swag fully supports Go modules and resolves imports through the module graph.

## Sources
- https://github.com/swaggo/swag
- https://github.com/swaggo/gin-swagger

---
Source: https://tokrepo.com/en/workflows/asset-49c03b2d
Author: Script Depot