apigen

package
v1.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2026 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIDefinition 

type APIDefinition struct {
	Name               string            `json:"name"`
	Description        string            `json:"description"`
	BaseURLs           []string          `json:"baseUrls"`
	GlobalVariables    map[string]string `json:"globalVariables,omitempty"`
	Endpoints          []Endpoint        `json:"endpoints"`
	OutputFileBaseName string            `json:"-"` // Not serialized but used for exports
	OutputFolder       string            `json:"-"` // Not serialized but used for exports
	// contains filtered or unexported fields
}

APIDefinition represents a complete API with base URL and endpoints

func LoadFromFile 

func LoadFromFile(filename string) (*APIDefinition, error)

LoadFromFile loads an API definition from a JSON file

func New added in v1.17.83 

func New(name, description string) *APIDefinition

New starts a new API definition with sensible defaults: docs are written to ./docs with a file name derived from the API name. Override with Output().

func NewAPIDefinition 

func NewAPIDefinition(name, description string, baseURLs []string, outputFolder, outputFileName string) *APIDefinition

NewAPIDefinition creates a new API definition with the given name and base URLs

func (*APIDefinition) AddEndpoint 

func (api *APIDefinition) AddEndpoint(endpoint Endpoint) *APIDefinition

AddEndpoint adds a new endpoint to the API definition

func (*APIDefinition) AddGlobalVariable 

func (api *APIDefinition) AddGlobalVariable(name, value string) *APIDefinition

AddGlobalVariable adds a global variable to the API definition

func (*APIDefinition) DELETE added in v1.17.83 

func (api *APIDefinition) DELETE(path, summary string) *Route

DELETE starts building a DELETE endpoint.

func (*APIDefinition) Err added in v1.17.83 

func (api *APIDefinition) Err() error

Err returns the first error encountered while building endpoints via the fluent API, if any. ExportAll also returns it, so checking there is enough.

func (*APIDefinition) ExportAll 

func (api *APIDefinition) ExportAll() error

ExportAll exports to all supported formats

func (*APIDefinition) ExportToMarkdown 

func (api *APIDefinition) ExportToMarkdown() error

ExportToMarkdown exports the API definition to a Markdown file

func (*APIDefinition) ExportToOpenAPI 

func (api *APIDefinition) ExportToOpenAPI() error

ExportToOpenAPI exports the API definition to an OpenAPI JSON file

func (*APIDefinition) ExportToPostman 

func (api *APIDefinition) ExportToPostman() error

ExportToPostman exports the API definition to a Postman collection

func (*APIDefinition) GET added in v1.17.83 

func (api *APIDefinition) GET(path, summary string) *Route

GET starts building a GET endpoint.

func (*APIDefinition) Output added in v1.17.83 

func (api *APIDefinition) Output(folder, baseName string) *APIDefinition

Output sets the folder and base file name for exported docs.

func (*APIDefinition) PATCH added in v1.17.83 

func (api *APIDefinition) PATCH(path, summary string) *Route

PATCH starts building a PATCH endpoint.

func (*APIDefinition) POST added in v1.17.83 

func (api *APIDefinition) POST(path, summary string) *Route

POST starts building a POST endpoint.

func (*APIDefinition) PUT added in v1.17.83 

func (api *APIDefinition) PUT(path, summary string) *Route

PUT starts building a PUT endpoint.

func (*APIDefinition) Route added in v1.17.83 

func (api *APIDefinition) Route(method, path, summary string) *Route

Route starts building an endpoint for an arbitrary HTTP method. Useful when the method is only known at runtime; otherwise prefer GET/POST/etc.

func (*APIDefinition) SaveToFile 

func (api *APIDefinition) SaveToFile() error

SaveToFile saves the API definition to a JSON file

func (*APIDefinition) Servers added in v1.17.83 

func (api *APIDefinition) Servers(urls ...string) *APIDefinition

Servers appends base URLs the API is served from.

func (*APIDefinition) Var added in v1.17.83 

func (api *APIDefinition) Var(name, value string) *APIDefinition

Var adds a global variable (alias of AddGlobalVariable).

type Auth 

type Auth struct {
	Type        string            `json:"type"` // bearer, basic, apiKey, oauth2
	Description string            `json:"description,omitempty"`
	Parameters  map[string]string `json:"parameters,omitempty"`
}

Auth defines authentication details

type ContentType 

type ContentType string
const (
	ContentTypeJSON              ContentType = "application/json"
	ContentTypeXML               ContentType = "application/xml"
	ContentTypeFormURLEncoded    ContentType = "application/x-www-form-urlencoded"
	ContentTypeMultipartFormData ContentType = "multipart/form-data"
	ContentTypeTextPlain         ContentType = "text/plain"
	ContentTypeTextHTML          ContentType = "text/html"
	ContentTypeOctetStream       ContentType = "application/octet-stream"
	ContentTypeJPEG              ContentType = "image/jpeg"
	ContentTypePNG               ContentType = "image/png"
	ContentTypeGIF               ContentType = "image/gif"
)

type Endpoint 

type Endpoint struct {
	Path           string             `json:"path"`
	Method         string             `json:"method"`
	Summary        string             `json:"summary"`
	Description    string             `json:"description"`
	Headers        map[Headers]string `json:"headers,omitempty"`
	QueryParams    []Parameter        `json:"queryParams,omitempty"`
	PathParams     []Parameter        `json:"pathParams,omitempty"` // New field for path parameters
	RequestBody    *RequestBody       `json:"requestBody,omitempty"`
	Responses      []Response         `json:"responses"`
	Authentication *Auth              `json:"authentication,omitempty"`
}

Endpoint represents a single API endpoint

type FieldOverride 

type FieldOverride struct {
	Name        string `json:"name"`
	JsonName    string `json:"jsonName,omitempty"`
	Type        string `json:"type,omitempty"`
	Required    *bool  `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
	Example     any    `json:"example,omitempty"`
	Exclude     bool   `json:"exclude,omitempty"`
	IsNewField  bool   `json:"isNewField,omitempty"` // Add this field
}

FieldOverride allows overriding specific fields in a struct

type Headers 

type Headers string
const (
	HeaderPrivateToken    Headers = "Private-Token"
	HeaderContentType     Headers = "Content-Type"
	HeaderAccept          Headers = "Accept"
	HeaderUserAgent       Headers = "User-Agent"
	HeaderAuthorization   Headers = "Authorization"
	HeaderCacheControl    Headers = "Cache-Control"
	HeaderContentLength   Headers = "Content-Length"
	HeaderContentEncoding Headers = "Content-Encoding"
	HeaderContentLanguage Headers = "Content-Language"
	HeaderContentLocation Headers = "Content-Location"
)

type KarmaHeaders 

type KarmaHeaders map[Headers]string

type ParamOption added in v1.17.83 

type ParamOption func(*Parameter)

ParamOption customizes a Parameter built by Query/PathParam.

func ParamExample added in v1.17.83 

func ParamExample(ex string) ParamOption

ParamExample sets a parameter's example value.

func ParamRequired added in v1.17.83 

func ParamRequired() ParamOption

ParamRequired marks a parameter as required.

func ParamType added in v1.17.83 

func ParamType(t string) ParamOption

ParamType sets a parameter's type (default "string").

type Parameter 

type Parameter struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Required    bool   `json:"required"`
	Description string `json:"description,omitempty"`
	Example     string `json:"example,omitempty"`
}

Parameter defines a request parameter (query or path param)

type RequestBody 

type RequestBody struct {
	ContentType ContentType        `json:"contentType"`
	Required    bool               `json:"required"`
	Schema      json.RawMessage    `json:"schema,omitempty"`
	Example     json.RawMessage    `json:"example,omitempty"`
	Fields      []RequestBodyField `json:"fields,omitempty"` // Structured field definitions
}

RequestBody defines the structure of a request body

func RequestBodyFromStruct 

func RequestBodyFromStruct(structPtr any, contentType ContentType, required bool, overrides []FieldOverride) (*RequestBody, error)

RequestBodyFromStruct creates a RequestBody from a struct type

type RequestBodyField 

type RequestBodyField struct {
	Name        string             `json:"name"`
	JsonName    string             `json:"jsonName"`
	Type        string             `json:"type"`
	Required    bool               `json:"required"`
	Description string             `json:"description,omitempty"`
	Example     any                `json:"example,omitempty"`
	Fields      []RequestBodyField `json:"fields,omitempty"` // For nested objects
}

RequestBodyField represents a single field in a request body

type RespOption added in v1.17.83 

type RespOption func(*Response)

RespOption customizes a Response built by Response/OK/Fail/etc.

func RespHeader added in v1.17.83 

func RespHeader(key Headers, example string) RespOption

RespHeader documents a response header and its example value.

type Response 

type Response struct {
	StatusCode  int                `json:"statusCode"`
	Description string             `json:"description"`
	Headers     map[Headers]string `json:"headers,omitempty"`
	ContentType ContentType        `json:"contentType,omitempty"`
	Schema      json.RawMessage    `json:"schema,omitempty"`
	Example     json.RawMessage    `json:"example,omitempty"`
	Fields      []RequestBodyField `json:"fields,omitempty"` // Reusing the same field structure
}

Response defines a possible API response

func ResponseFromStruct 

func ResponseFromStruct(statusCode int, description string, structPtr any, contentType ContentType, overrides []FieldOverride) (*Response, error)

ResponseFromStruct creates a Response from a struct type

type Route added in v1.17.83 

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

Route accumulates one endpoint. Create it with api.GET/POST/etc., chain configuration, and finish with Add().

func (*Route) Add added in v1.17.83 

func (r *Route) Add() *APIDefinition

Add finalizes the route, appends it to the API definition, and returns the API for further chaining.

func (*Route) Auth added in v1.17.83 

func (r *Route) Auth(kind string, description ...string) *Route

Auth marks the endpoint as requiring authentication of the given type (e.g. "bearer", "apiKey"). The description is optional.

func (*Route) Bearer added in v1.17.83 

func (r *Route) Bearer(description ...string) *Route

Bearer is shorthand for Auth("bearer", ...).

func (*Route) Body added in v1.17.83 

func (r *Route) Body(v any, overrides ...FieldOverride) *Route

Body sets the JSON request body from a struct. Field examples are generated automatically; pass overrides to tweak specific fields.

func (*Route) Created added in v1.17.83 

func (r *Route) Created(body any, description ...string) *Route

Created adds a 201 response. description defaults to "Created".

func (*Route) Desc added in v1.17.83 

func (r *Route) Desc(d string) *Route

Desc sets the long-form description.

func (*Route) Fail added in v1.17.83 

func (r *Route) Fail(status int, description string, body any, opts ...RespOption) *Route

Fail adds an error response. Pass nil body for no content.

func (*Route) Header added in v1.17.83 

func (r *Route) Header(key Headers, example string) *Route

Header documents a request header and its example value.

func (*Route) NoContent added in v1.17.83 

func (r *Route) NoContent(description ...string) *Route

NoContent adds a 204 response with no body.

func (*Route) OK added in v1.17.83 

func (r *Route) OK(body any, description ...string) *Route

OK adds a 200 response. description defaults to "OK".

func (*Route) PathParam added in v1.17.83 

func (r *Route) PathParam(name, description string, opts ...ParamOption) *Route

PathParam describes a path parameter richly. Parameters present in the path are auto-detected on Add even without this; use it to add a type/example.

func (*Route) Query added in v1.17.83 

func (r *Route) Query(name, description string, opts ...ParamOption) *Route

Query documents a query parameter.

func (*Route) Response added in v1.17.83 

func (r *Route) Response(status int, description string, body any, opts ...RespOption) *Route

Response documents a response whose JSON body is generated from a struct. Pass nil for body when the response has no content.

Source Files

View all Source files

Directories

Path Synopsis
Package fiberspec is the bridge between a Fiber server and apigen docs.
 Package fiberspec is the bridge between a Fiber server and apigen docs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.