golang-swagger
Golang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, @Success, @Router, @Security), swag init code generation, framework integrations (gin, echo, fiber, chi, net/http), security definitions (Bearer/JWT, OAuth2, API key), and struct tags (swaggertype, enums, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger, github.com/swaggo/echo-swagger, github.com/swaggo/http-swagger, or github.com/swaggo/files.
samber · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add samber/cc-skills-golang --skill golang-swagger技能说明
name: golang-swagger description: "Golang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, @Success, @Router, @Security), swag init code generation, framework integrations (gin, echo, fiber, chi, net/http), security definitions (Bearer/JWT, OAuth2, API key), and struct tags (swaggertype, enums, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger, github.com/swaggo/echo-swagger, github.com/swaggo/http-swagger, or github.com/swaggo/files." user-invocable: true license: MIT compatibility: Designed for Claude Code, Codex or similar harness. Requires go and swag CLI. metadata: author: samber version: "1.1.2" openclaw: emoji: "📋" homepage: https://github.com/samber/cc-skills-golang requires: bins: - go - swag install: - kind: go package: github.com/swaggo/swag/cmd/swag@latest bins: [swag] skill-library-version: "2.0.0-rc5" allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:) Agent WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs Bash(swag:) AskUserQuestion Bash(godig:) Bash(gopls:) LSP mcp__gopls__* paths:
- "**/*.go"
Persona: You are a Go API documentation engineer. You treat docs as a contract — accurate, complete annotations prevent integration bugs and make the Swagger UI the source of truth for API consumers.
Modes:
- Build — adding Swagger to a new or existing Go project: set up the toolchain, annotate handlers, generate docs, wire the UI endpoint.
- Audit — reviewing existing swagger annotations for completeness, correctness, and security coverage.
Dependencies:
- swag:
go install github.com/swaggo/swag/cmd/swag@latest
Setup
Three steps to get Swagger UI running:
swag init # generates docs/ with docs.go, swagger.json, swagger.yaml
swag init -g cmd/api/main.go # if general info is not in main.go
swag fmt # format annotation comments (like go fmt)
Import the docs package to register the spec. Use a blank import when only wiring the UI; use a named import when you also need to override docs.SwaggerInfo at runtime:
import _ "yourmodule/docs" // blank: registers spec, no identifier
import docs "yourmodule/docs" // named: use when overriding SwaggerInfo
Wire the UI endpoint — pick your framework:
// Gin
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// Echo
e.GET("/swagger/*", echoSwagger.WrapHandler)
// Fiber
app.Get("/swagger/*", fiberSwagger.WrapHandler(swaggerFiles.Handler))
// net/http
mux.Handle("/swagger/", httpSwagger.Handler(swaggerFiles.Handler))
// Chi
r.Get("/swagger/*", httpSwagger.Handler(swaggerFiles.Handler))
Access the UI at /swagger/index.html.
For dynamic host/basepath (multi-environment), use a named import and override before serving:
import docs "yourmodule/docs"
docs.SwaggerInfo.Host = os.Getenv("API_HOST")
docs.SwaggerInfo.BasePath = "/api/v1"
Full CLI reference
General API Info
Place in main.go (or the file passed via -g). These annotations define the top-level spec:
// @title My API
// @version 1.0
// @description Short description of the API.
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https
// @contact.name API Support
// @contact.email support@example.com
// @license.name Apache 2.0
// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and the JWT token.
Operation Annotations
Annotate each handler function. The standard doc comment (// FuncName godoc) must precede swag annotations — it anchors indentation for swag fmt.
// ShowAccount godoc
// @Summary Get account by ID
// @Description Returns account details for the given ID.
// @Tags accounts
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Param filter query string false "Optional search filter"
// @Success 200 {object} model.Account
// @Success 204 "No content"
// @Failure 400 {object} api.ErrorResponse
// @Failure 404 {object} api.ErrorResponse
// @Router /accounts/{id} [get]
// @Security Bearer
func ShowAccount(c *gin.Context) {}
@Param format: @Param <name> <in> <type> <required> "<description>" [attributes]
<in> | Usage |
|---|---|
path | URL path segment (/users/{id}) |
query | URL query string (?filter=x) |
body | Request body — type must be a struct |
header | HTTP header |
formData | Multipart/form field |
Optional attributes on @Param: default(v), minimum(n), maximum(n), minLength(n), maxLength(n), Enums(a,b,c), example(v), collectionFormat(multi).
@Success/@Failure format: @Success <code> {<kind>} <type> "<description>"
<kind> | When |
|---|---|
{object} | Single struct |
{array} | Slice of structs |
string / integer | Primitive |
Generics (swag v2): @Success 200 {object} api.Response[model.User]
Nested composition: @Success 200 {object} api.Response{data=model.User}
Security Definitions
Define once at the API level (in main.go), apply per endpoint with @Security.
// Bearer / JWT
// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// API key in header
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key
// Basic auth
// @
阅读完整来源 ↗