---
name: "swag-go-restful-api-swagger-docs"
description: "Generate Swagger 2.0 and OpenAPI 3.0 specs from Go code comments using Swag CLI."
metadata:
  author: "Swaggo"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "generate swagger docs swag"
  - "annotate go function swagger"
  - "gin-swagger setup"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Swag Automated OpenAPI & Swagger Documentation for Go

Configures Swag: adding declarative comments to main.go and controller functions (@Summary, @Description, @Param, @Success), generating docs with swag init, and serving interactive Swagger UI via gin-swagger.

## When to Invoke
Invoke this skill whenever you need to:
- generate swagger docs swag
- annotate go function swagger
- gin-swagger setup

## Execution SOP & Rules
1. Add general API annotations in main.go: // @title My API // @version 1.0 // @host localhost:8080.
2. Annotate handlers: // @Summary Get user // @Param id path int true 'User ID' // @Success 200 {object} User.
3. Generate documentation artifacts: swag init.
4. Mount handler in Gin: r.GET('/swagger/*', ginSwagger.WrapHandler(swaggerFiles.Handler)).

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.