analyzer

Documentation

Index

• Constants
• func BuildDocument(title, version, server string, endpoints []Endpoint, examples bool, ...) *spec.Document
• func Load(dir string, patterns ...string) ([]*packages.Package, error)
• type Detector
• type Endpoint
• type FormField
• type Handler
• type Options
• type RawRoute
• type Reflector
  • func NewReflector() *Reflector
  • func (r *Reflector) Schema(t types.Type) *spec.Schema
• type Result
  • func Generate(dir string, patterns []string, opts Options) (*Result, error)

Constants

const LoadMode = packages.NeedName |
	packages.NeedFiles |
	packages.NeedImports |
	packages.NeedDeps |
	packages.NeedModule |
	packages.NeedSyntax |
	packages.NeedTypes |
	packages.NeedTypesInfo

LoadMode is the set of package facts the analyzer needs: full type info and syntax trees for the target packages and their dependencies.

Functions

func BuildDocument

func BuildDocument(title, version, server string, endpoints []Endpoint, examples bool, marshalers map[types.Object]*spec.Schema) *spec.Document

BuildDocument turns inferred endpoints into an OpenAPI 3.1 document, reflecting request/response types into reusable component schemas. server sets the spec's servers[].url; when empty a valid templated default is emitted.

func Load

func Load(dir string, patterns ...string) ([]*packages.Package, error)

Load type-checks the packages matching patterns (e.g. "./...") and returns them. Loaded packages are returned even when some contain errors; the error result aggregates those so callers can choose to continue best-effort.

Types

type Detector

type Detector interface {
	// Name identifies the framework (e.g. "chi", "net/http").
	Name() string
	// Detect returns the routes registered in pkg.
	Detect(pkg *packages.Package) []RawRoute
}

Detector finds routes registered for one web framework within a package.

type Endpoint

type Endpoint struct {
	Method           string
	Path             string
	Tag              string // controller/feature grouping, derived from the handler's package
	PathParams       []string
	PathParamTypes   map[string]types.Type // path param name -> type, when bound via a struct
	QueryParams      []string
	QueryParamTypes  map[string]types.Type // query param name -> type, when bound via a struct
	HeaderParams     []string
	HeaderParamTypes map[string]types.Type // header param name -> type, when bound via a struct
	CookieParams     []string
	// RequiredParams marks query/header params declared required (gin binding /
	// validate tags). Keys are "query:<name>" or "header:<name>".
	RequiredParams map[string]bool
	RequestType    types.Type // nil if none detected
	// FormParams describe a form/multipart request body (FormFile/FormValue/
	// PostForm). When non-empty the body is emitted under FormContentType
	// instead of application/json.
	FormParams      []FormField
	FormContentType string
	Responses       map[int]types.Type // status code -> body type (nil = no content)
	// ResponseContentType overrides a response's media type (non-JSON responses
	// such as text/plain from c.String / w.Write). Keyed by status code.
	ResponseContentType map[int]string
	// ResponseHeaders lists response header names set by the handler, attached to
	// the primary success response.
	ResponseHeaders []string
	Security        []authScheme // detected auth requirements (empty if none)
	Warnings        []string
}

Endpoint is a fully resolved operation ready to be turned into OpenAPI.

type FormField

type FormField struct {
	Name string
	Type types.Type
	File bool
}

FormField is one field of a form/multipart request body. File marks a file upload (schema string/binary); Type carries a non-string scalar type when known.

type Handler

type Handler struct {
	Body *ast.BlockStmt
	Pkg  *packages.Package
}

Handler is a resolved handler function with the package context needed to type-check expressions inside its body.

type Options

type Options struct {
	Title   string
	Version string
	// Server, when set, is emitted as the spec's single servers[].url. When
	// empty a valid templated default ({baseUrl}) is emitted so import tools
	// stop inventing a malformed base URL.
	Server string
	// Examples, when true, synthesizes sample values for component and inline
	// schemas (maps render as {"key1":v1,...}, structs as field samples).
	Examples bool
}

Options configures a generation run.

type RawRoute

type RawRoute struct {
	Method     string     // upper-case HTTP method
	Path       string     // OpenAPI-style path, e.g. /users/{id}
	Handler    ast.Expr   // the handler argument expression
	Middleware []ast.Expr // route- and group-level middleware expressions, if any
	Pkg        *packages.Package
	Pos        token.Pos
}

RawRoute is a route discovered by a framework detector, before its handler is resolved and its request/response types inferred.

type Reflector

type Reflector struct {
	// Components accumulates named struct schemas keyed by type name. The caller
	// places this map under components/schemas in the final document.
	Components map[string]*spec.Schema
	// contains filtered or unexported fields
}

Reflector converts go/types.Type values into spec.Schema values. Named struct types are registered once in Components and referenced elsewhere via $ref, so the resulting OpenAPI document stays compact and cycle-safe.

func NewReflector

func NewReflector() *Reflector

NewReflector returns a Reflector with initialised state.

func (*Reflector) Schema

func (r *Reflector) Schema(t types.Type) *spec.Schema

Schema returns the OpenAPI schema for t, registering named structs as a side effect. A nil type yields an empty (permissive) schema.

type Result

type Result struct {
	Document *spec.Document
	Warnings []string
}

Result is the output of Generate: the document plus any best-effort warnings (unresolved handlers, dynamic routes, inference gaps).

func Generate

func Generate(dir string, patterns []string, opts Options) (*Result, error)

Generate loads the packages under dir matching patterns, discovers routes across all supported frameworks, infers their schemas, and returns an OpenAPI 3.1 document.