go-doc

go-doc is a standalone tool that converts go-zero .api files into OpenAPI specifications.

Originally part of the go-zero project, go-doc is now an independent, easy-to-use command-line tool for generating API documentation in both Swagger 2.0 and OpenAPI 3.0 formats.

✨ Features

• 🚀 Standalone Binary - No dependencies on go-zero runtime
• 📝 Dual Specification Support - Generate both Swagger 2.0 and OpenAPI 3.0 formats
• 🎯 Rich Type Support - Handles structs, arrays, maps, pointers, and nested types
• 🏷️ Tag-based Configuration - Support for json, form, path, header tags
• 📊 Advanced Validations - Range, enum, default, example values
• 🔐 Security Definitions - Custom authentication configurations
• 📦 Multiple Output Formats - JSON or YAML output
• 🎨 Definition References - Optional use of definitions/schemas for cleaner output
• 🔄 Automatic Conversion - Seamless conversion from Swagger 2.0 to OpenAPI 3.0

📦 Installation

From Source

git clone https://github.com/danielchan-25/go-doc.git
cd go-doc
go build -o bin/go-doc ./cmd/go-doc

Using Go Install

go install github.com/danielchan-25/go-doc/cmd/go-doc@latest

🚀 Quick Start

Basic Usage

# Generate Swagger 2.0 (default)
go-doc -a example/example.api -d output

# Generate OpenAPI 3.0
go-doc -a example/example.api -d output -s openapi3.0

# Generate YAML format
go-doc -a example/example.api -d output -y

# Generate OpenAPI 3.0 in YAML
go-doc -a example/example.api -d output -s openapi3.0 -y

# Specify custom filename
go-doc -a example/example.api -d output -f my-api

Command Line Options

Flags:
  -a, --api string            API file path (required)
  -d, --dir string            Output directory (required)
  -f, --filename string       Output filename without extension (optional, defaults to API filename)
  -h, --help                  help for go-doc
  -s, --spec-version string   OpenAPI specification version: swagger2.0 or openapi3.0 (default "swagger2.0")
  -v, --version               version for go-doc
  -y, --yaml                  Generate YAML format instead of JSON

Specification Versions

Swagger 2.0 (Default)

go-doc -a example/example.api -d output
# or explicitly
go-doc -a example/example.api -d output -s swagger2.0

OpenAPI 3.0

go-doc -a example/example.api -d output -s openapi3.0

Key Differences:

• Swagger 2.0: Uses host, basePath, schemes at root level
• OpenAPI 3.0: Uses servers array with complete URLs
• Swagger 2.0: Definitions under definitions
• OpenAPI 3.0: Schemas under components/schemas
• Swagger 2.0: Security definitions under securityDefinitions
• OpenAPI 3.0: Security schemes under components/securitySchemes
• OpenAPI 3.0: Request bodies are separated from parameters

📖 API File Format

Basic Structure

syntax = "v1"

info (
    title:       "My API"
    description: "API documentation"
    version:     "v1.0.0"
    host:        "api.example.com"
    basePath:    "/v1"
)

type (
    UserRequest {
        Id   int    `json:"id,range=[1:10000]"`
        Name string `json:"name"`
    }
    UserResponse {
        Id   int    `json:"id"`
        Name string `json:"name"`
    }
)

@server (
    tags: "user"
)
service MyAPI {
    @handler getUser
    get /user/:id (UserRequest) returns (UserResponse)
}

Supported Info Properties

• title - API title
• description - API description
• version - API version
• host - API host (e.g., "api.example.com")
• basePath - Base path (e.g., "/v1")
• schemes - Protocols (e.g., "http,https")
• consumes - Request content types
• produces - Response content types
• contactName, contactURL, contactEmail - Contact information
• licenseName, licenseURL - License information
• useDefinitions - Use Swagger definitions (true/false)
• wrapCodeMsg - Wrap response in {code, msg, data} structure
• securityDefinitionsFromJson - Security definitions in JSON format

Tag Options

JSON Tags

type Example {
    // Range validation
    Age int `json:"age,range=[1:150]"`
    
    // Default value
    Status string `json:"status,default=active"`
    
    // Example value
    Email string `json:"email,example=user@example.com"`
    
    // Enum values
    Role string `json:"role,options=admin|user|guest"`
    
    // Optional field
    Phone string `json:"phone,optional"`
}

Form Tags

type QueryRequest {
    Keyword string `form:"keyword"`
    Page    int    `form:"page,default=1"`
    Size    int    `form:"size,range=[1:100]"`
}

Path Tags

type PathRequest {
    UserId int `path:"userId,range=[1:999999]"`
}

Header Tags

type HeaderRequest {
    Token string `header:"Authorization"`
}

🔧 Advanced Features

Security Definitions

info (
    securityDefinitionsFromJson: `{
        "apiKey": {
            "type": "apiKey",
            "name": "x-api-key",
            "in": "header",
            "description": "API Key Authentication"
        }
    }`
)

@server (
    authType: apiKey
)
service MyAPI {
    // Routes here will use apiKey authentication
}

Code-Msg Wrapper

info (
    wrapCodeMsg: true
    bizCodeEnumDescription: "1001-User not found<br>1002-Permission denied"
)

Response will be wrapped as:

{
    "code": 0,
    "msg": "ok",
    "data": { /* your actual response */ }
}

📂 Project Structure

go-doc/
├── cmd/
│   └── go-doc/          # Main entry point
│       └── main.go
├── internal/
│   ├── swagger/         # Core swagger generation logic
│   │   ├── swagger.go
│   │   ├── parameter.go
│   │   ├── path.go
│   │   └── ...
│   └── util/            # Internal utilities
│       ├── util.go
│       ├── stringx.go
│       └── pathx.go
├── example/             # Example API files
│   ├── example.api
│   └── example_cn.api
├── go.mod
└── README.md

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Original code from go-zero project
• Built on top of go-openapi/spec

📧 Contact

For questions or issues, please open an issue on GitHub.

---

Made with ❤️ by extracting and enhancing go-zero's swagger generation capabilities.