parser

Documentation

Overview

Package parser provides AST parsing capabilities for Go source files. It identifies handlers marked with special comments and extracts their metadata for code generation.

Index

• Constants
• type Field
• type Handler
• type ParseResult
  • func ExtractFromGeneric(generic *coreast.ParseResult) (*ParseResult, error)
• type Parser
  • func New() *Parser
  • func (p *Parser) ParseFile(filename string) (*ParseResult, error)
• type Source
• type Struct

Constants

const (
	// SourcePath indicates the parameter comes from URL path
	// Example: // in:path
	SourcePath = "path"

	// SourceQuery indicates the parameter comes from query string
	// Example: // in:query
	SourceQuery = "query"

	// SourceHeader indicates the parameter comes from HTTP headers
	// Example: // in:header
	SourceHeader = "header"

	// SourceCookie indicates the parameter comes from cookies
	// Example: // in:cookie
	SourceCookie = "cookie"

	// SourceForm indicates the parameter comes from form data
	// Example: // in:form
	SourceForm = "form"

	// SourceBody indicates the parameter is the request body
	// Example: // in:body
	SourceBody = "body"
)

Field Source Comments These comments indicate where parameters come from in HTTP requests

const (
	// TagPath is the struct tag for path parameters
	// Example: `path:"userId"`
	TagPath = "path"

	// TagQuery is the struct tag for query parameters
	// Example: `query:"filter"`
	TagQuery = "query"

	// TagHeader is the struct tag for header parameters
	// Example: `header:"X-API-Key"`
	TagHeader = "header"

	// TagCookie is the struct tag for cookie parameters
	// Example: `cookie:"session_id"`
	TagCookie = "cookie"

	// TagForm is the struct tag for form fields
	// Example: `form:"title"`
	TagForm = "form"

	// TagJSON is the struct tag for JSON fields
	// Example: `json:"name"`
	TagJSON = "json"

	// TagValidate is the struct tag for validation rules
	// Example: `validate:"required,email"`
	TagValidate = "validate"
)

Struct Tags Used in struct field tags for parameter extraction

const (
	// FieldNameRequest is the name for *http.Request fields
	FieldNameRequest = "Request"
	// FieldNameReq is an alias for Request
	FieldNameReq = "Req"

	// FieldNameResponseWriter is the name for http.ResponseWriter fields
	FieldNameResponseWriter = "ResponseWriter"
	// FieldNameResponse is an alias for ResponseWriter
	FieldNameResponse = "Response"
	// FieldNameWriter is an alias for ResponseWriter
	FieldNameWriter = "Writer"
	// FieldNameRes is an alias for ResponseWriter
	FieldNameRes = "Res"

	// FieldNameRawBody is the name for raw body []byte fields
	FieldNameRawBody = "RawBody"
	// FieldNameRaw is an alias for RawBody
	FieldNameRaw = "Raw"
)

Special Field Names Field names that have special meaning in handlers

const (
	// TypeFileHeader is the type for single file uploads
	TypeFileHeader = "*multipart.FileHeader"

	// TypeFileHeaderSlice is the type for multiple file uploads
	TypeFileHeaderSlice = "[]*multipart.FileHeader"
)

File Types Go types for file upload fields

const (
	// DefaultMaxMemory is the default max memory for multipart form parsing (32MB)
	DefaultMaxMemory = 33554432

	// CommentPrefix is the prefix for extracting "in:xxx" comments
	CommentPrefix = "in:"

	// CommentPrefixDefault is the prefix for extracting "default:xxx" comments
	CommentPrefixDefault = "default:"
)

Default Values

const (
	// DirectiveHandler marks a function as an HTTP handler for code generation
	DirectiveHandler = "apikit:handler"
)

Handler Directive

Types

type Field

type Field struct {
	// Name is the field name
	Name string

	// Type is the Go type (e.g., "string", "*int", "[]string")
	Type string

	// StructTag is the complete struct tag string (e.g., `json:"name" query:"q" validate:"required"`)
	// Extractors should use reflect.StructTag(field.StructTag).Lookup() to get specific tags
	StructTag string

	// Comment-based annotations (e.g., // in:query, // in:path userId)
	InComment     string // Source extracted from "// in:xxx" comment (e.g., "query", "path")
	InCommentName string // Optional parameter name from "// in:xxx paramName" comment

	// Type information
	IsPointer bool   // Is this a pointer type (*string)
	IsSlice   bool   // Is this a slice type ([]string)
	SliceType string // Element type for slices

	// Special field types
	IsEmbedded       bool // Embedded struct
	IsBody           bool // Marked with "// in: body" comment
	IsRawBody        bool // Field named RawBody with type []byte
	IsResponseWriter bool // Field is http.ResponseWriter
	IsRequest        bool // Field is *http.Request
	IsFile           bool // Field is *multipart.FileHeader or []*multipart.FileHeader

	// Nested struct information
	NestedStruct *Struct // If this field is a struct type, contains its definition
	PackagePath  string  // Import path for the type (e.g., "myapp/pagination")
}

Field represents a struct field with its tags and metadata

type Handler

type Handler struct {
	// Name is the function name
	Name string

	// Package is the package name where the handler is defined
	Package string

	// Receiver is the receiver type for methods (empty for functions)
	Receiver string

	// ParamType is the type of the request parameter
	ParamType string

	// ReturnType is the return type of the handler
	ReturnType string

	// Struct contains the parsed request struct information
	Struct *Struct

	// HasResponseWriter indicates if handler has http.ResponseWriter parameter
	HasResponseWriter bool

	// HasRequest indicates if handler has *http.Request parameter
	HasRequest bool

	// Position in source file (for error reporting)
	Pos token.Position
}

Handler represents a function marked with apikit:handler comment

type ParseResult

type ParseResult struct {
	// Handlers found in the file
	Handlers []Handler

	// Structs found in the file (including DTOs)
	Structs map[string]*Struct

	// Source information
	Source Source

	// Errors encountered during parsing (non-fatal)
	Warnings []string
}

ParseResult contains the results of parsing a file

func ExtractFromGeneric

func ExtractFromGeneric(generic *coreast.ParseResult) (*ParseResult, error)

ExtractFromGeneric extracts APIKit-specific information from generic parse result This adapter filters for apikit:handler and apikit:dto directives

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser analyzes Go source files to find apikit handlers

func New

func New() *Parser

New creates a new Parser instance

func (*Parser) ParseFile

func (p *Parser) ParseFile(filename string) (*ParseResult, error)

ParseFile analyzes a single Go file and extracts handler information

type Source

type Source struct {
	// Filename is the source file path
	Filename string

	// Package is the package name
	Package string
}

Source represents information about where the handler was found

type Struct

type Struct struct {
	// Name is the struct name
	Name string

	// Fields are the struct fields
	Fields []Field

	// IsDTO indicates if this struct is marked with apikit:dto comment
	IsDTO bool
}

Struct represents a request struct with its fields