Go Quick Start

Get started with Bytedocs in Go applications

Bytedocs for Go supports the most popular frameworks with zero-configuration auto-detection.

Supported Frameworks

  • Gin - The fastest full-featured web framework
  • Echo - High performance, minimalist framework
  • Fiber - Express-inspired framework built on Fasthttp
  • Gorilla Mux - Powerful URL router and dispatcher
  • net/http - Standard library HTTP server

Installation

go get github.com/aibnuhibban/bytedocs-go

Quick Start Examples

Gin Framework

package main

import (
    "github.com/aibnuhibban/bytedocs/pkg/core"
    "github.com/aibnuhibban/bytedocs/pkg/parser"
    "github.com/gin-gonic/gin"
)

type User struct {
    ID    int    `json:"id" example:"1"`
    Name  string `json:"name" example:"John Doe" binding:"required"`
    Email string `json:"email" example:"john@example.com"`
}

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

    // Setup Bytedocs - One line!
    parser.SetupGinDocs(r, &core.Config{
        Title:       "My API",
        Version:     "1.0.0",
        Description: "My awesome API documentation",
    })

    // Define your routes as normal
    r.GET("/users/:id", getUser)
    r.POST("/users", createUser)

    r.Run(":8080")
}

func getUser(c *gin.Context) {
    user := User{ID: 1, Name: "John", Email: "john@example.com"}
    c.JSON(200, user)
}

func createUser(c *gin.Context) {
    var user User
    c.BindJSON(&user)
    c.JSON(201, user)
}

Echo Framework

package main

import (
    "github.com/aibnuhibban/bytedocs/pkg/core"
    "github.com/aibnuhibban/bytedocs/pkg/parser"
    "github.com/labstack/echo/v4"
)

func main() {
    e := echo.New()

    // Setup Bytedocs
    parser.SetupEchoDocs(e, &core.Config{
        Title:   "My Echo API",
        Version: "1.0.0",
    })

    e.GET("/users/:id", getUser)
    e.POST("/users", createUser)

    e.Start(":8080")
}

func getUser(c echo.Context) error {
    user := User{ID: 1, Name: "John"}
    return c.JSON(200, user)
}

func createUser(c echo.Context) error {
    var user User
    c.Bind(&user)
    return c.JSON(201, user)
}

Fiber Framework

package main

import (
    "github.com/aibnuhibban/bytedocs/pkg/core"
    "github.com/aibnuhibban/bytedocs/pkg/parser"
    "github.com/gofiber/fiber/v2"
)

func main() {
    app := fiber.New()

    // Setup Bytedocs
    parser.SetupFiberDocs(app, &core.Config{
        Title:   "My Fiber API",
        Version: "1.0.0",
    })

    app.Get("/users/:id", getUser)
    app.Post("/users", createUser)

    app.Listen(":8080")
}

func getUser(c *fiber.Ctx) error {
    user := User{ID: 1, Name: "John"}
    return c.JSON(user)
}

func createUser(c *fiber.Ctx) error {
    var user User
    c.BodyParser(&user)
    return c.Status(201).JSON(user)
}

Gorilla Mux

package main

import (
    "encoding/json"
    "net/http"

    "github.com/aibnuhibban/bytedocs/pkg/core"
    "github.com/aibnuhibban/bytedocs/pkg/parser"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    // Setup Bytedocs
    parser.SetupGorillaDocs(r, &core.Config{
        Title:   "My Gorilla API",
        Version: "1.0.0",
    })

    r.HandleFunc("/users/{id}", getUser).Methods("GET")
    r.HandleFunc("/users", createUser).Methods("POST")

    http.ListenAndServe(":8080", r)
}

func getUser(w http.ResponseWriter, r *http.Request) {
    user := User{ID: 1, Name: "John"}
    json.NewEncoder(w).Encode(user)
}

func createUser(w http.ResponseWriter, r *http.Request) {
    var user User
    json.NewDecoder(r.Body).Decode(&user)
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

Configuration Options

Basic Configuration

config := &core.Config{
    Title:       "My API",
    Version:     "1.0.0",
    Description: "API description",
    DocsPath:    "/docs",        // Default: "/docs"
    AutoDetect:  true,            // Default: true
}

Multiple Environments

config := &core.Config{
    Title:   "My API",
    Version: "1.0.0",
    BaseURLs: []core.BaseURLOption{
        {Name: "Production", URL: "https://api.example.com"},
        {Name: "Staging", URL: "https://staging.example.com"},
        {Name: "Local", URL: "http://localhost:8080"},
    },
}

With Authentication

config := &core.Config{
    Title:   "My API",
    Version: "1.0.0",
    AuthConfig: &core.AuthConfig{
        Enabled:  true,
        Type:     "session",
        Username: "admin",
        Password: "secret",
    },
}

Auto-Detection Features

Bytedocs automatically detects:

1. Route Information

  • HTTP method (GET, POST, PUT, DELETE, etc.)
  • Path with parameters (/users/:id)
  • Handler function

2. Request Parameters

Path Parameters:

r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")  // Auto-detected as path parameter
    // ...
})

Query Parameters:

r.GET("/users", func(c *gin.Context) {
    page := c.Query("page")  // Auto-detected as query parameter
    // ...
})

Headers:

r.GET("/users", func(c *gin.Context) {
    auth := c.GetHeader("Authorization")  // Auto-detected
    // ...
})

3. Request Body

type CreateUserRequest struct {
    Name  string `json:"name" binding:"required"`
    Email string `json:"email" binding:"required"`
    Age   int    `json:"age" binding:"min=0,max=150"`
}

r.POST("/users", func(c *gin.Context) {
    var req CreateUserRequest
    c.BindJSON(&req)  // Auto-detected as request body
    // ...
})

4. Response Types

type UserResponse struct {
    ID    int    `json:"id" example:"123"`
    Name  string `json:"name" example:"John Doe"`
    Email string `json:"email" example:"john@example.com"`
}

r.GET("/users/:id", func(c *gin.Context) {
    user := UserResponse{ID: 1, Name: "John", Email: "john@example.com"}
    c.JSON(200, user)  // Auto-detected: status 200, UserResponse schema
})

Struct Tags for Better Documentation

JSON Tags

type User struct {
    ID   int    `json:"id"`           // Field name in JSON
    Name string `json:"name"`
    Age  int    `json:"age,omitempty"` // Optional field
}

Example Tags

type User struct {
    ID    int    `json:"id" example:"123"`
    Name  string `json:"name" example:"John Doe"`
    Email string `json:"email" example:"john@example.com"`
}

Validation Tags

type CreateUser struct {
    Name  string `json:"name" binding:"required"`
    Email string `json:"email" binding:"required,email"`
    Age   int    `json:"age" binding:"min=0,max=150"`
}

Description in Comments

type User struct {
    // User's unique identifier
    ID int `json:"id"`

    // Full name of the user
    Name string `json:"name"`

    // Email address (must be unique)
    Email string `json:"email"`
}

Manual Route Registration

For complex cases, you can manually add routes:

docs := core.NewAPIDocs(config)

docs.AddRoute("GET", "/custom", nil,
    core.WithSummary("Custom endpoint"),
    core.WithDescription("A manually registered endpoint"),
    core.WithParameters([]core.Parameter{
        {
            Name:        "id",
            In:          "path",
            Required:    true,
            Type:        "integer",
            Description: "User ID",
        },
    }),
    core.WithResponse(200, "Success", userSchema),
)

Visit Documentation

Start your server and visit:

http://localhost:8080/docs

What's Next?

Edit this page
Getting Started
Get Bytedocs running in under 5 minutes
Laravel Quick Start
Get started with Bytedocs in Laravel applications