{
  "slug": "Add-Swagger-to-a-Golang-Gin-Project-0cad93295e0e",
  "title": "Add Swagger to a Golang Gin Project",
  "subtitle": "In the earlier stage of the project, we implemented middleware components and a health monitoring controller. In this tutorial, I will…",
  "excerpt": "In the earlier stage of the project, we implemented middleware components and a health monitoring controller. In this tutorial, I will…",
  "date": "2025-08-15",
  "tags": [
    "Go"
  ],
  "readingTime": "2 min",
  "url": "https://medium.com/@mobinshaterian/add-swagger-to-a-golang-gin-project-0cad93295e0e",
  "hero": "https://cdn-images-1.medium.com/max/800/1*d4oQBmzQJNplvQ6vaCScZA.jpeg",
  "content": [
    {
      "type": "heading",
      "level": 2,
      "text": "Add Swagger to a Golang Gin Project"
    },
    {
      "type": "paragraph",
      "html": "In the earlier stage of the project, we implemented middleware components and a health monitoring controller. In this tutorial, I will build on this foundation by integrating Swagger, a tool that enables interactive API documentation and streamlines the processes of testing and development."
    },
    {
      "type": "heading",
      "level": 3,
      "text": "Swagger repository"
    },
    {
      "type": "code",
      "lang": "text",
      "code": "https://github.com/swaggo/swag"
    },
    {
      "type": "image",
      "src": "https://cdn-images-1.medium.com/max/800/1*d4oQBmzQJNplvQ6vaCScZA.jpeg",
      "alt": "Add Swagger to a Golang Gin Project",
      "caption": "",
      "width": 1120,
      "height": 1120
    },
    {
      "type": "heading",
      "level": 3,
      "text": "Prevoius document"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "✅ Step 1: Install swag CLI"
    },
    {
      "type": "paragraph",
      "html": "Install the <code>swag</code> command-line tool globally:"
    },
    {
      "type": "code",
      "lang": "bash",
      "code": "go install github.com/swaggo/swag/cmd/swag@latest"
    },
    {
      "type": "quote",
      "html": "<em>Make sure </em><code><em>$GOPATH/bin</em></code><em> is in your </em><code><em>$PATH</em></code><em>, otherwise you won't be able to run </em><code><em>swag</em></code><em> directly.</em>"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "✅ Step 2: Add Swagger annotations to your handlers"
    },
    {
      "type": "paragraph",
      "html": "Use comments to annotate your API routes. Example:"
    },
    {
      "type": "code",
      "lang": "go",
      "code": "// @title           My API// @version         1.0// @description     This is a sample API with Gin\nand Swagger.// @host              localhost:8080// @BasePath         /api/v1package main"
    },
    {
      "type": "code",
      "lang": "go",
      "code": "func main() {\n    r := gin.Default()\n    // Serve Swagger docs\n    r.GET(\"/swagger/*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n    r.Run(\":4000\")\n}"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "✅ Step 3: Install Gin Swagger middleware"
    },
    {
      "type": "code",
      "lang": "bash",
      "code": "go get github.com/swaggo/gin-swagger\ngo get github.com/swaggo/files\ngo get github.com/swaggo/swag"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "✅ Step 4: Generate Swagger docs"
    },
    {
      "type": "code",
      "lang": "text",
      "code": "swag init --parseDependency --parseInternal -g cmd/web/main.go"
    },
    {
      "type": "image",
      "src": "https://cdn-images-1.medium.com/max/800/1*gE2fjUubf366rgG06ksnMw.png",
      "alt": "Add Swagger to a Golang Gin Project",
      "caption": "",
      "width": 1297,
      "height": 856
    },
    {
      "type": "embed",
      "provider": "youtube",
      "url": "https://www.youtube.com/embed/_eF4ErisR-Q?feature=oembed"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "Swagger URL 🧑‍🎓"
    },
    {
      "type": "code",
      "lang": "text",
      "code": "http://127.0.0.1:4000/swagger/index.html#/"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "Add Setup Configuration"
    },
    {
      "type": "code",
      "lang": "go",
      "code": "func (a *Application) Routes() {\n    api := a.Router.Group(\"/api/v1/\") api.GET(\"/health\", HealthHandler) api.GET(\"/slow\",\n    SlowHandler) // Set Swagger metadata dynamically docs.SwaggerInfo.Title = \"My API\"\n    docs.SwaggerInfo.Version = \"1.0\" docs.SwaggerInfo.Description =\n    \"This is a sample API with Gin and Swagger.\" docs.SwaggerInfo.Host = \"127.0.0.1:4000\"\n    docs.SwaggerInfo.BasePath = \"/api/v1\" docs.SwaggerInfo.Schemes = []string{\n        \"http\"\n    }\n    // or {\n        \"https\"\n    }\n    in production a.Router.GET(\"/swagger/*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n}"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "Github Commit"
    },
    {
      "type": "heading",
      "level": 2,
      "text": "Conclusion 🧙"
    },
    {
      "type": "paragraph",
      "html": "Integrating Swagger into a Golang Gin project significantly enhances API development and testing by providing clear, interactive, and up-to-date documentation. By following a few simple steps — installing the Swag CLI, adding descriptive annotations to your handlers, installing the necessary Gin Swagger middleware, and generating the documentation — you can quickly enable a powerful self-documenting API system."
    },
    {
      "type": "paragraph",
      "html": "In this tutorial, we built upon a previous foundation that included middleware and a health controller, and successfully added Swagger support to visualize and interact with API endpoints in real time. The use of dynamic configuration through <code>docs.SwaggerInfo</code> allows for flexible deployment across different environments, making it easy to manage settings like host, base path, and schemes."
    },
    {
      "type": "paragraph",
      "html": "With Swagger now integrated, developers can explore, test, and debug API routes directly from the browser, improving collaboration between teams and reducing the learning curve for new contributors. Overall, Swagger paired with Gin offers a robust solution for modern API development in Go, combining speed, clarity, and functionality in one cohesive package."
    }
  ]
}