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/ci-cd-workflows.md
View on GitHub# Swagger CI/CD — GitHub Actions Workflows and Hooks
GitHub Actions for auto-generating docs, PR validation, Makefile targets, and pre-commit hook.
## GitHub Actions — Generate and Commit
Auto-generate and commit docs on push to `main`:
```yaml
name: swagger-docs
on:
push:
branches: [main]
paths: ['**/*.go']
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
- uses: actions/setup-go@v5
with:
go-version: '1.24'
cache: true
- name: Install swag
run: go install github.com/swaggo/swag/cmd/swag@latest
- name: Generate docs
run: swag init -g cmd/api/main.go -d ./,./internal/... --exclude ./vendor
- name: Commit if changed
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add docs/
git diff --staged --quiet || git commit -m "docs: regenerate swagger"
git push
```
## GitHub Actions — PR Validation
Fail the PR if swagger docs are stale:
```yaml
name: swagger-check
on:
pull_request:
paths: ['**/*.go']
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.24'
cache: true
- name: Install swag
run: go install github.com/swaggo/swag/cmd/swag@latest
- name: Check docs are up to date
run: |
swag init -g cmd/api/main.go -d ./,./internal/... --exclude ./vendor
git diff --exit-code docs/ || {
echo "::error::Swagger docs are stale. Run 'make docs' and commit the changes."
exit 1
}
```
## Makefile Integration
```makefile
.PHONY: docs docs-check docs-serve
# Generate swagger docs
docs:
swag fmt
swag init -g cmd/api/main.go -d ./,./internal/... --exclude ./vendor
# Validate docs are committed (used in CI)
docs-check:
swag init -g cmd/api/main.go -d ./,./internal/... --exclude ./vendor
git diff --exit-code docs/
# Serve swagger UI locally (requires the app to be running)
docs-serve:
@echo "Swagger UI: http://localhost:8080/swagger/index.html"
```
## Pre-commit Hook
Auto-regenerate docs before each commit:
```bash
#!/bin/sh
# .git/hooks/pre-commit
# Check if any Go files changed
STAGED_GO=$(git diff --cached --name-only --diff-filter=ACM | grep '\.go$')
if [ -z "$STAGED_GO" ]; then
exit 0
fi
# Regenerate docs
swag fmt
swag init -g cmd/api/main.go -d ./,./internal/... --exclude ./vendor
# Stage updated docs
git add docs/
```
Make executable: `chmod +x .git/hooks/pre-commit`
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: 322k | 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 |