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)
• type Endpoint
  • func (e *Endpoint) APIAuth() bool
  • func (e *Endpoint) CookieAuth() bool
• 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() []reflect.Type
  • 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.
	PackageName 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. 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
	// MethodName is the name of method of the service interface which handles the business logic of
	// this endpoint.
	// It must fulfill the Go language specification for method names
	// (https://go.dev/ref/spec#MethodName)
	// TODO: Should we rename this field to be something like ServiceMethodName?
	MethodName string
	// RequestName is the name of the method used to name the method in the client side code. When not
	// set, MethodName is used.
	// TODO: Should we delete this field in favor of always using MethodName?
	RequestName  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
}

Endpoint represents endpoint's configuration.

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.

type EndpointGroup

type EndpointGroup struct {
	Name   string
	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.

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() []reflect.Type

All returns a slice containing every top-level type and their dependencies.

TODO: see how to have a better implementation for adding to seen, uniqueNames, and all.

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.