APISpec: Generate OpenAPI from Go code

<!-- markdownlint-disable MD033 --> <div align="center"> <img src="logo.png" alt="APISpec Logo" width="200"> </div> <!-- markdownlint-enable MD033 -->

APISpec analyzes your Go code and automatically generates an OpenAPI 3.1 spec (YAML or JSON). It detects routes for popular frameworks (Gin, Echo, Chi, Fiber, net/http), follows call graphs to the final handlers, and infers request/response types from real code (struct tags, literals, generics, and more).

TL;DR: Point APISpec at your module. Get an OpenAPI spec and, optionally, an interactive call-graph diagram.

🎬 Demo Video

Click the image above to watch the full demo on YouTube

Features

• Automated OpenAPI: Generate OpenAPI 3.1 from real Go code.
• Framework-aware: Detects Gin, Echo, Chi, Fiber, and net/http automatically.
• Accurate by analysis: Builds a call graph to resolve handlers, parameters, bodies, and responses.
• Configurable: YAML config plus CLI flags; flags always win.
• Visualize: Optional HTML call-graph diagram for debugging.
• Extensible: Pattern-based framework config; add new frameworks without changing core logic.
• Smart Type Resolution: Automatically resolves underlying primitive types for aliases and enums.
• Array Type Support: Comprehensive handling of Go arrays including fixed-size arrays ([16]byte) and variable-length arrays ([...]int).
• External Type Resolution: Automatically resolves external package types to their underlying primitives while preserving internal project types.
• Validator Tag Support: Comprehensive support for go-playground/validator tags with automatic OpenAPI constraint mapping.
• Function Literal Analysis: Full support for anonymous functions in route handlers.
• Comprehensive Error Handling: Robust handling of edge cases and invalid inputs.
• Performance Profiling: Built-in CPU, memory, block, mutex, and trace profiling for performance analysis.
• Configurable Limits: Fine-tune analysis limits for large codebases with detailed warning messages.
• CGO Support: Skip CGO packages during analysis to avoid build errors.

Note: Generating call-graph diagrams and metadata files consumes additional resources and time.

Framework Support

Gorilla Mux

• [x] Route registration: Detects HandleFunc and Handle calls with path and handler arguments
• [x] Handler function detection: Identifies handler functions passed as arguments to route registration
• [x] HTTP method extraction: Automatically extracts HTTP methods from handler function names or explicit method calls
• [x] Path parameter detection: Recognizes path parameters in route patterns (e.g., /users/{id})
• [x] Subrouter support: Handles nested routing with PathPrefix and Subrouter
• [ ] Parameter extraction: Path parameters are not yet fully resolved to handler function parameters
• [ ] Conditional routing: Dynamic route registration based on runtime conditions is not supported

Other Frameworks

• [x] Gin: Full support for route registration, and parameter handling
• [x] Chi: Full support for route mounting, grouping, parameter extraction, and render package integration
• [x] Echo: Full support for route registration, grouping, and parameter handling
• [x] Fiber: Full support for route registration, grouping, and parameter handling
• [x] Standard net/http: Basic support for HandleFunc and Handle calls

Golang Feature Support

APISpec focuses on practical coverage for real-world services. Current coverage includes:

• [x] Alias imports: supports import aliases in analysis.
• [x] Alias types: type aliases are detected and resolved to underlying primitive types.
• [x] Enum resolution: automatically resolves enum types to their underlying primitive types (string, int, etc.) from constants, enum tags, or oneof validator tags.
• [x] Assignment and alias tracking: short :=, =, multi-assign, tuple returns, latest-wins resolution, alias chains, and shadowing.
• [ ] Conditional methods: detecting HTTP methods set via switch/if around net/http Handle/HandleFunc is not supported.
• [x] Composite literals / maps / slices / arrays: recognizes literal and container types for schema mapping.
• [x] Array type support: comprehensive handling of fixed-size arrays ([16]byte, [5]int) and variable-length arrays ([...]int).
• [x] Dependency injection: supports route grouping mounted via dependency injection.
• [ ] Duplicate status codes: paths with the same status code and different schemas are not yet supported.
• [x] External type introspection: types from external packages are automatically resolved to their underlying primitives; complex external types can be defined via externalTypes in config.
• [x] Generics (functions): detects type parameters and maps concrete types at call sites.
• [ ] Generics (types): generic struct and type instantiation are partially supported.
• [ ] Inferred status codes: status codes assigned via variables are not inferred.
• [x] Interfaces: captures interface types and methods; unresolved dynamic values are represented generically.
• [x] Chain calls: efficiently processes method chaining and establishes parent-child relationships in the call graph.
• [x] Nested calls: handles chained/method calls and nested expressions.
• [x] Parameter tracing across calls: follows arguments across the call graph; maps function parameters to call arguments.
• [ ] Interface param resolution: interface type parameters in functions are not yet fully resolved to concrete types.
• [ ] Parent object type tracing: limited ability to trace the receiver/parent type; Decode on non-body targets may be misclassified.
• [x] Pointers and dereference: detects *T and automatically dereferences when configured.
• [x] Selectors and field access: resolves pkg.Type.Field and nested selectors where possible.
• [x] Struct fields: reads field types, embedded fields, and struct tags (json, xml, form, etc.).
• [x] Nested struct types: supports anonymous nested structs within struct fields, preserving complete type information for accurate schema generation.
• [x] Function and method return types: automatically resolves and captures return types from function signatures, enabling accurate type resolution in pattern matchers.
• [x] CGO support: includes a flag to skip CGO packages during analysis, useful for projects with complex C dependencies.
• [x] Function literals: supports anonymous functions (func literals) in route handlers and call analysis.
• [x] Validator tag support: comprehensive support for go-playground/validator tags including validation rules, constraints, and enum definitions.

Type Resolution Examples

APISpec automatically resolves underlying types for aliases and enums:

// Enum types are resolved to their underlying primitive type
type AllowedUserType string

const (
    UserTypeAdmin AllowedUserType = "admin"
    UserTypeCustomer AllowedUserType = "user"
)

// In your struct, AllowedUserTypes will be resolved to []string
type Permission struct {
    ID                string
    Resource          string
    Operation         string
    AllowedUserTypes  []domain.AllowedUserType  // Resolves to []string
}

// Generated OpenAPI schema:
// AllowedUserTypes:
//   type: array
//   items:
//     type: string

// Pointer aliases are also resolved
type UserID *int64

type User struct {
    ID UserID  // Resolves to integer
}

// Generated OpenAPI schema:
// ID:
//   type: integer
//   format: int64

Array Type Support

APISpec provides comprehensive support for Go arrays, including fixed-size arrays and variable-length arrays:

// Fixed-size byte arrays are converted to string with maxLength
type User struct {
    ID       [16]byte  // Converts to string with format: "byte", maxLength: 16
    Token    [32]byte  // Converts to string with format: "byte", maxLength: 32
    Scores   [5]int    // Converts to array with maxItems: 5, minItems: 5
    Tags     [10]string // Converts to array with maxItems: 10, minItems: 10
}

// Variable-length arrays
type Config struct {
    Values [...]int    // Converts to array without size constraints
}

Generated