henriqueatila/golang-gin-best-practices / skills/golang-gin-swagger
golang-gin-swagger
VerifiedSwagger/OpenAPI docs for Go Gin with swaggo/swag. Use when adding API docs, Swagger UI, endpoint annotations, or generating swagger.json for a Gin application.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| metadata.json | config | 492 B |
| references/annotations-advanced.md | markdown | 4.0 KB |
| references/annotations-crud-auth.md | markdown | 5.1 KB |
| references/annotations-extras.md | markdown | 2.8 KB |
| references/annotations-params-responses.md | markdown | 3.5 KB |
| references/annotations-responses.md | markdown | 2.2 KB |
| references/ci-cd-tooling.md | markdown | 4.6 KB |
| references/ci-cd-workflows.md | markdown | 2.7 KB |
| references/setup-models-generate.md | markdown | 3.4 KB |
| references/setup-serve.md | markdown | 2.7 KB |
references/setup-serve.md
View on GitHub# Swagger Setup — Dependencies, Serving UI, and Handler Annotations
Installation, serving Swagger UI in Gin, dynamic host configuration, and core handler annotation examples.
## Dependencies
```bash
# CLI tool (generates docs from annotations)
go install github.com/swaggo/swag/cmd/swag@latest
# Go module dependencies
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
```
Ensure `$(go env GOPATH)/bin` is in your `$PATH` so the `swag` CLI is available.
## General API Annotations
Place directly before `main()` in `cmd/api/main.go`. Only one annotation block per project.
```go
// @title My API
// @version 1.0
// @description Production-grade REST API built with Gin.
// @contact.name API Support
// @contact.email support@example.com
// @license.name MIT
// @license.url https://opensource.org/licenses/MIT
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description Enter: Bearer {token}
func main() { ... }
```
## Serving Swagger UI
```go
package main
import (
"os"
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "myapp/docs" // CRITICAL: blank import registers the generated spec
)
func main() {
r := gin.New()
// Only expose Swagger UI outside production
if os.Getenv("GIN_MODE") != "release" {
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
// ... register routes, start server
}
```
Access at: `http://localhost:8080/swagger/index.html`
**Swagger UI options:**
```go
r.GET("/swagger/*any", ginSwagger.WrapHandler(
swaggerFiles.Handler,
ginSwagger.URL("/swagger/doc.json"),
ginSwagger.DocExpansion("list"), // "list"|"full"|"none"
ginSwagger.DeepLinking(true),
ginSwagger.DefaultModelsExpandDepth(1), // -1 hides models section
ginSwagger.PersistAuthorization(true), // retains Bearer token across reloads
ginSwagger.DefaultModelExpandDepth(1),
ginSwagger.DefaultModelRendering("example"), // "example"|"model"
))
```
## Dynamic Host Configuration
Override spec values at runtime for multi-environment deploys:
```go
import (
"os"
"myapp/docs"
)
func main() {
docs.SwaggerInfo.Host = os.Getenv("API_HOST") // e.g. "api.prod.example.com"
docs.SwaggerInfo.Schemes = []string{"https"}
docs.SwaggerInfo.BasePath = "/api/v1"
// ...
}
```
For handler annotation examples (Create, GetByID, List) and model struct tags: see [setup-models-generate.md](setup-models-generate.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |