gin-docs

Gin Docs

Zero-annotation API documentation generator for Go applications using Gin and GORM.

Gin Docs automatically introspects your Gin router, reads struct tags via reflection, generates a valid OpenAPI 3.1 specification, and serves interactive documentation — all with a single function call.

Features

• Zero annotations — no comment-based docs. Everything is inferred from code.
• One-line mount — gindocs.Mount(router, db) and you're done.
• Two UI options — Swagger UI (default) and Scalar, switchable via config or query param.
• Full OpenAPI 3.1 — valid spec that works with any tooling.
• GORM integration — auto-generates Create/Update schema variants from your models.
• Smart inference — auto-generates summaries, status codes, examples, and parameter descriptions.
• Fluent override API — customize any route's documentation with a builder pattern.
• Export support — download as Postman or Insomnia collections.
• Production-ready — concurrent-safe, no panics, proper caching.

Quick Start

go get github.com/MUKE-coder/gin-docs

package main

import (
    "net/http"

    "github.com/MUKE-coder/gin-docs/gindocs"
    "github.com/gin-gonic/gin"
)

type User struct {
    ID    uint   `json:"id" gorm:"primarykey"`
    Name  string `json:"name" binding:"required"`
    Email string `json:"email" binding:"required,email"`
}

func main() {
    r := gin.Default()

    r.GET("/api/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, []User{{ID: 1, Name: "John", Email: "[email protected]"}})
    })

    r.POST("/api/users", func(c *gin.Context) {
        var u User
        if err := c.ShouldBindJSON(&u); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        u.ID = 1
        c.JSON(http.StatusCreated, u)
    })

    r.GET("/api/users/:id", func(c *gin.Context) {
        c.JSON(http.StatusOK, User{ID: 1, Name: "John", Email: "[email protected]"})
    })

    // One line to add docs!
    gindocs.Mount(r, nil)

    r.Run(":8080")
    // Visit http://localhost:8080/docs
}

Configuration

gindocs.Mount(router, db, gindocs.Config{
    Title:       "My API",
    Description: "API description in markdown.",
    Version:     "1.0.0",
    UI:          gindocs.UIScalar, // or gindocs.UISwagger (default)
    DevMode:     true,             // Re-introspect on every request
    ReadOnly:    false,            // Disable "Try It" if true
    Auth: gindocs.AuthConfig{
        Type:         gindocs.AuthBearer,
        BearerFormat: "JWT",
    },
    Servers: []gindocs.ServerInfo{
        {URL: "http://localhost:8080", Description: "Local"},
    },
    Models: []interface{}{User{}, Post{}}, // GORM models
})

Config Reference

Struct Tags

Gin Docs reads these struct tags to generate accurate schemas:

type User struct {
    ID    uint   `json:"id" gorm:"primarykey"`
    Name  string `json:"name" binding:"required,min=2,max=100"`
    Email string `json:"email" binding:"required,email" gorm:"size:200;uniqueIndex"`
    Role  string `json:"role" binding:"oneof=admin user" gorm:"default:'user'"`
    Bio   string `json:"bio" docs:"description:User biography,example:A Go developer"`
}

Route Overrides

Customize documentation for specific routes:

docs := gindocs.Mount(r, nil, config)

docs.Route("POST /api/users").
    Summary("Register a new user").
    Description("Creates a user account.").
    RequestBody(CreateUserInput{}).
    Response(201, User{}, "User created").
    Response(400, nil, "Validation error").
    Tags("Authentication")

docs.Group("/api/admin/*").
    Tags("Admin").
    Security("bearerAuth")

Doc Middleware

Document routes inline with a middleware helper:

r.POST("/api/users",
    gindocs.Doc(gindocs.DocConfig{
        Summary:     "Create user",
        RequestBody: CreateUserInput{},
        Response:    User{},
    }),
    createUserHandler,
)

GORM Models

When you register GORM models, Gin Docs automatically generates three schema variants:

• User — full model (for responses, includes ID and timestamps)
• CreateUser — without ID, CreatedAt, UpdatedAt (for request bodies)
• UpdateUser — all fields optional (for PATCH requests)

gindocs.Mount(r, db, gindocs.Config{
    Models: []interface{}{User{}, Post{}, Comment{}},
})

UI Switching

Switch between Swagger UI and Scalar:

// Via config
gindocs.Config{UI: gindocs.UIScalar}

// Via query parameter
// http://localhost:8080/docs?ui=scalar
// http://localhost:8080/docs?ui=swagger

Endpoints

Examples

• Basic example — minimal setup
• Full example — all features configured
• Demo app — realistic blog API

License

MIT License. See LICENSE for details.