swaggo/swag

★ 12,789GoAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((repo))
    What it does
      Generate Swagger docs
      Read code annotations
      Serve interactive UI
    Frameworks
      Gin Echo Fiber
      Other Go routers
    Features
      REST endpoint docs
      Security schemes
      Complex type support
    Workflow
      Add comment blocks
      Run swag init
      Import docs package

mindmap root((repo)) What it does Generate Swagger docs Read code annotations Serve interactive UI Frameworks Gin Echo Fiber Other Go routers Features REST endpoint docs Security schemes Complex type support Workflow Add comment blocks Run swag init Import docs package

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Generate interactive Swagger UI docs for a Gin or Echo REST API without maintaining a separate spec file

USE CASE 2

Auto-document API endpoints, request parameters, and response types from Go struct annotations that stay in sync with the code

Tech stack

Getting it running

Difficulty · easy Time to first run · 30min

Requires an existing Go web project with a framework like Gin or Echo, install the swag CLI via go install.

In plain English

swag is a command-line tool for Go developers that reads special annotation comments in your source code and automatically generates API documentation in the Swagger 2.0 format. Swagger is a widely used standard for describing what an HTTP API does: which endpoints exist, what parameters they accept, what data they return, and how authentication works. Swagger documentation can be served as an interactive web panel where other developers can browse and test your API without writing any code themselves. Rather than maintaining this specification in a separate file, swag lets you keep the descriptions alongside your code and regenerate the docs as the codebase changes. The basic workflow is: add structured comments above your API handler functions using a format swag recognizes, then run swag init from your project root. This command parses your Go files, finds the annotations, and produces a docs/ folder containing a docs.go file plus JSON and YAML versions of the API specification. You import that generated file into your project so a Swagger UI panel can serve the documentation in a browser. swag supports a range of annotation types. You can document general API info (title, version, contact, license, base URL), individual operations (route, HTTP method, parameters, request body, response codes and types), and security schemes like API keys or OAuth. Complex Go types, arrays, generics, nested structs, and embedded types are all handled. Plugins connect swag to popular Go web frameworks including Gin, Echo, Fiber, and others, so the generated documentation wires into the framework's routing with minimal setup. A separate swag fmt command formats your annotation comments consistently, the same way gofmt standardizes Go code across a team. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

Add swag annotation comments to my Gin REST API handlers and walk me through running swag init to generate the docs/ folder and serve Swagger UI

Prompt 2

Write a swag comment block for a POST /users endpoint that accepts a JSON body with name and email fields and returns a 201 with the created user object

Prompt 3

Set up swag with the Fiber web framework and configure it to serve Swagger UI at /swagger/index.html with authentication schemes documented

Open on GitHub → Explain another repo

← swaggo on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.