golang-swagger

The golang-swagger skill provides comprehensive support for integrating OpenAPI/Swagger documentation into Go projects using the swaggo/swag toolchain. It enables developers to generate interactive API documentation directly from annotated Go source code, eliminating the need to manually maintain separate specification files. By adding structured comment annotations above handler functions, the skill automatically produces swagger.json and swagger.yaml files that power a fully functional Swagger UI, making API exploration and testing seamless for both developers and API consumers.

This skill covers the complete workflow from initial setup to advanced configurations. It supports all major Go web frameworks including Gin, Echo, Fiber, Chi, and net/http, providing framework-specific integration patterns. The skill handles annotation syntax for endpoints (@Summary, @Param, @Success, @Router), request/response schemas with struct tags, security definitions (Bearer/JWT, OAuth2, API keys), and code generation commands. It also includes best practices for organizing annotations, formatting them with swag fmt, and dynamically configuring API hosts and base paths for multi-environment deployments.

Target users include backend engineers building RESTful APIs in Go, DevOps teams maintaining API gateways, and technical writers responsible for API documentation. The skill is particularly valuable when onboarding new projects that need documentation from scratch, auditing existing codebases for annotation completeness, or ensuring security schemes are properly documented. It treats API documentation as a contract, emphasizing accuracy and completeness to prevent integration issues and establish the Swagger UI as the authoritative reference for API consumers.