apigen

Documentation

Index

• Constants
• func TypescriptTypeName(t reflect.Type) string
• type API
  • func (a *API) Group(name, prefix string) *EndpointGroup
  • func (api *API) MustWriteDocs(path string)
  • func (a *API) MustWriteGo(path string)
  • func (a *API) MustWriteTS(path string)
  • func (a *API) MustWriteTSMock(path string)
• type Endpoint
  • func (e *Endpoint) APIAuth() bool
  • func (e *Endpoint) CookieAuth() bool
  • func (e *Endpoint) Validate() error
• type EndpointGroup
  • func (eg *EndpointGroup) Delete(path string, endpoint *Endpoint)
  • func (eg *EndpointGroup) Get(path string, endpoint *Endpoint)
  • func (eg *EndpointGroup) Patch(path string, endpoint *Endpoint)
  • func (eg *EndpointGroup) Post(path string, endpoint *Endpoint)
• type Param
  • func NewParam(name string, instance interface{}) Param
• type StringBuilder
  • func (s *StringBuilder) Writelnf(format string, a ...interface{})
• type Types
  • func NewTypes() Types
  • func (types *Types) All() map[reflect.Type]string
  • func (types *Types) GenerateTypescriptDefinitions() string
  • func (types *Types) Register(t reflect.Type)

Constants

const DateFormat = "2006-01-02T15:04:05.999Z"

DateFormat is the layout of dates passed into and out of the API.

Functions

func TypescriptTypeName

func TypescriptTypeName(t reflect.Type) string

TypescriptTypeName gets the corresponding TypeScript type for a provided reflect.Type. If the type is an anonymous struct, it returns an empty string.

Types

type API

type API struct {
	// Version is the corresponding version of the API.
	// It's concatenated to the BasePath, so assuming the base path is "/api" and the version is "v1"
	// the API paths will begin with `/api/v1`.
	// When empty, the version doesn't appear in the API paths. If it starts or ends with one or more
	// "/", they are stripped from the API endpoint paths.
	Version     string
	Description string
	// The package name to use for the Go generated code.
	// If omitted, the last segment of the PackagePath will be used as the package name.
	PackageName string
	// The path of the package that will use the generated Go code.
	// This is used to prevent the code from importing its own package.
	PackagePath string
	// BasePath is the  base path for the API endpoints. E.g. "/api".
	// It doesn't require to begin with "/". When empty, "/" is used.
	BasePath       string
	Auth           api.Auth
	EndpointGroups []*EndpointGroup
}

API represents specific API's configuration.

func (*API) Group

func (a *API) Group(name, prefix string) *EndpointGroup

Group adds new endpoints group to API. name must be `^([A-Z0-9]\w*)?$“ prefix must be `^\w*$`.

func (*API) MustWriteDocs

func (api *API) MustWriteDocs(path string)

MustWriteDocs generates API documentation and writes it to the specified file path. If an error occurs, it panics.

func (*API) MustWriteGo

func (a *API) MustWriteGo(path string)

MustWriteGo writes generated Go code into a file. If an error occurs, it panics.

func (*API) MustWriteTS

func (a *API) MustWriteTS(path string)

MustWriteTS writes generated TypeScript code into a file indicated by path. The generated code is an API client to run in the browser.

If an error occurs, it panics.

func (*API) MustWriteTSMock

func (a *API) MustWriteTSMock(path string)

MustWriteTSMock writes generated TypeScript code into a file indicated by path. The generated code is an API client mock to run in the browser.

If an error occurs, it panics.

type Endpoint

type Endpoint struct {
	// Name is a free text used to name the endpoint for documentation purpose.
	// It cannot be empty.
	Name string
	// Description is a free text to describe the endpoint for documentation purpose.
	Description string
	// GoName is an identifier used by the Go generator to generate specific server side code for this
	// endpoint.
	//
	// It must start with an uppercase letter and fulfill the Go language specification for method
	// names (https://go.dev/ref/spec#MethodName).
	// It cannot be empty.
	GoName string
	// TypeScriptName is an identifier used by the TypeScript generator to generate specific client
	// code for this endpoint
	//
	// It must start with a lowercase letter and can only contains letters, digits, _, and $.
	// It cannot be empty.
	TypeScriptName string
	NoCookieAuth   bool
	NoAPIAuth      bool
	// Request is the type that defines the format of the request body.
	Request interface{}
	// Response is the type that defines the format of the response body.
	Response interface{}
	// QueryParams is the list of query parameters that the endpoint accepts.
	QueryParams []Param
	// PathParams is the list of path parameters that appear in the path associated with this
	// endpoint.
	PathParams []Param
	// ResponseMock is the data to use as a response for the generated mocks.
	// It must be of the same type than Response.
	// If a mock generator is called it must not be nil unless Response is nil.
	ResponseMock interface{}
}

Endpoint represents endpoint's configuration.

Passing an anonymous type to the fields that define the request or response will make the API generator to panic. Anonymous types aren't allowed such as named structs that have fields with direct or indirect of anonymous types, slices or arrays whose direct or indirect elements are of anonymous types.

func (*Endpoint) APIAuth

func (e *Endpoint) APIAuth() bool

APIAuth returns endpoint's API auth status.

func (*Endpoint) CookieAuth

func (e *Endpoint) CookieAuth() bool

CookieAuth returns endpoint's cookie auth status.

func (*Endpoint) Validate

func (e *Endpoint) Validate() error

Validate validates the endpoint fields values are correct according to the documented constraints.

type EndpointGroup

type EndpointGroup struct {
	// Name is the group name.
	//
	// Go generator uses it as part of type, functions, interfaces names, and in code comments.
	// The casing is adjusted according where it's used.
	//
	// TypeScript generator uses it as part of types names for the API functionality of this group.
	// The casing is adjusted according where it's used.
	//
	// Document generator uses as it is.
	Name string
	// Prefix is a prefix used for
	//
	// Go generator uses it as part of variables names, error messages, and the URL base path for the group.
	// The casing is adjusted according where it's used, but for the URL base path, lowercase is used.
	//
	// TypeScript generator uses it for composing the URL base path (lowercase).
	//
	// Document generator uses as it is.
	Prefix string
	// contains filtered or unexported fields
}

EndpointGroup represents endpoints group. You should always create a group using API.Group because it validates the field values to guarantee correct code generation.

func (*EndpointGroup) Delete

func (eg *EndpointGroup) Delete(path string, endpoint *Endpoint)

Delete adds new DELETE endpoint to endpoints group. It panics if path doesn't begin with '/'.

func (*EndpointGroup) Get

func (eg *EndpointGroup) Get(path string, endpoint *Endpoint)

Get adds new GET endpoint to endpoints group. It panics if path doesn't begin with '/'.

func (*EndpointGroup) Patch

func (eg *EndpointGroup) Patch(path string, endpoint *Endpoint)

Patch adds new PATCH endpoint to endpoints group. It panics if path doesn't begin with '/'.

func (*EndpointGroup) Post

func (eg *EndpointGroup) Post(path string, endpoint *Endpoint)

Post adds new POST endpoint to endpoints group. It panics if path doesn't begin with '/'.

type Param

type Param struct {
	Name string
	Type reflect.Type
}

Param represents string interpretation of param's name and type.

func NewParam

func NewParam(name string, instance interface{}) Param

NewParam constructor which creates new Param entity by given name and type through instance.

instance can only be a unsigned integer (of any size), string, uuid.UUID or time.Time, otherwise it panics.

type StringBuilder

type StringBuilder struct{ strings.Builder }

StringBuilder is an extension of strings.Builder that allows for writing formatted lines.

func (*StringBuilder) Writelnf

func (s *StringBuilder) Writelnf(format string, a ...interface{})

Writelnf formats arguments according to a format specifier and appends the resulting string to the StringBuilder's buffer.

type Types

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

Types handles generating definitions from types.

func NewTypes

func NewTypes() Types

NewTypes creates a new type definition generator.

func (*Types) All

func (types *Types) All() map[reflect.Type]string

All returns a map containing every top-level and their dependency types with their associated name.

func (*Types) GenerateTypescriptDefinitions

func (types *Types) GenerateTypescriptDefinitions() string

GenerateTypescriptDefinitions returns the TypeScript class definitions corresponding to the registered Go types.

func (*Types) Register

func (types *Types) Register(t reflect.Type)

Register registers a type for generation.