apigen

Documentation

Index

• Constants
• func LoadSetting[T any](key any, endpoint *FullEndpoint, defaultValue T) T
• 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 ClassField
  • func GetClassFieldsFromStruct(t reflect.Type) []ClassField
  • func (c *ClassField) String() string
• type Endpoint
  • 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)
  • func (eg *EndpointGroup) Put(path string, endpoint *Endpoint)
• type FullEndpoint
• type Middleware
• 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.

const OutputRootDirEnvOverride = "STORJ_APIGEN_OUTPUT_TO_DIR"

OutputRootDirEnvOverride is the name of the environment variable that can be used to override the root directory used for the api.Write... functions.

Functions

func LoadSetting

func LoadSetting[T any](key any, endpoint *FullEndpoint, defaultValue T) T

LoadSetting returns from endpoint.Settings the value assigned to key or returns defaultValue if the key doesn't exist.

It panics if key doesn't have a value of the type T.

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

	// OutputRootDir is the root directory that functions like WriteGo, WriteTS, and WriteDocs will use.
	// If defined, the OutputRootDirEnvOverride environment variable will be used instead.
	OutputRootDir string
}

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 ClassField

type ClassField struct {
	Name     string
	Type     reflect.Type
	TypeName string
	Optional bool
	Nullable bool
}

ClassField is a description of a field to generate a string representation of a TypeScript class field.

func GetClassFieldsFromStruct

func GetClassFieldsFromStruct(t reflect.Type) []ClassField

GetClassFieldsFromStruct takes a struct type and returns the list of Class fields definition to create a TypeScript class based on t JSON representation.

It panics if t is not a struct, it has embedded fields that aren't structs, it has JSON tags names which aren't unique (considering that embedded ones are flatten into the class), a non-embedded field has no JSON tag, or a JSON tag is malformed.

func (*ClassField) String

func (c *ClassField) String() string

String returns the c string representation.

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
	// 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{}
	// Settings is the data to pass to the middleware handlers to adapt the generated
	// code to this endpoints.
	//
	// Not all the middlware handlers need extra data. Some of them use this data to disable it in
	// some endpoints.
	Settings map[any]any
}

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) 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
	// Middleware is a list of additional processing of requests that apply to all the endpoints of this group.
	Middleware []Middleware
	// 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 '/'.

func (*EndpointGroup) Put

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

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

type FullEndpoint

type FullEndpoint struct {
	Endpoint
	Path   string
	Method string
}

FullEndpoint represents endpoint with path and method.

type Middleware

type Middleware interface {
	// Generate generates the code that the API generator adds to a handler endpoint before calling
	// the service.
	//
	// All the dependencies defined as struct fields of the implementation of this interface are
	// available as fields of the struct handler. The generated code is executed inside of the methods
	// of the struct handler, hence it has access to all its fields. The handler instance is available
	// through the variable name h. For example:
	//
	// type middlewareImpl struct {
	// 	 log  *zap.Logger // Import path: "go.uber.org/zap"
	//   auth api.Auth   // Import path: "storj.io/storj/private/api"
	// }
	//
	// The generated code can access to log and auth through h.log and h.auth.
	//
	// Each handler method where the code is executed has access to the following variables names:
	// ctx of type context.Context, w of type http.ResponseWriter, and r of type *http.Request.
	// Make sure to not declare variable with those names in the generated code unless that's wrapped
	// in a scope.
	Generate(api *API, group *EndpointGroup, ep *FullEndpoint) string
}

Middleware allows to generate custom code that's executed at the beginning of the handler.

The implementation must declare their dependencies through unexported struct fields which doesn't begin with underscore (_), except fields whose name is just underscore (the blank identifier). The API generator will add the import those dependencies and allow to pass them through the constructor parameters of the group handler implementation, except the fields named with the blank identifier that should be only used to import packages that the generated code needs.

The limitation of using fields with the blank identifier as its names is that those packages must at least to export a type, hence, it isn't possible to import packages that only export constants or variables.

Middleware implementation with the same struct field name and type will be handled as one parameter, so the dependency will be shared between them. If they have the same struct field name, but a different type, the API generator will panic. NOTE types are compared as [package].[type name], hence, package name collision are not handled and it will produce code that doesn't compile.

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.