oapispec

Documentation

Index

• func SwaggerGen(ctx context.Context, routes []*Route, conf *SwaggerGenConfig) *openapi3.T
• func SwaggerUIHTML(ctx context.Context, url string) []byte
• type APIRequest
• type FormParam
• type PathParam
• type QueryParam
• type Route
• type SwaggerGenConfig

Functions

func SwaggerGen

func SwaggerGen(ctx context.Context, routes []*Route, conf *SwaggerGenConfig) *openapi3.T

func SwaggerUIHTML

func SwaggerUIHTML(ctx context.Context, url string) []byte

Types

type APIRequest

type APIRequest struct {
	Ctx             context.Context
	Or              orchestrator.Orchestrator
	Req             *http.Request
	QP              map[string]string
	PP              map[string]string
	FP              map[string]string
	Filter          database.AndFilter
	Input           interface{}
	Part            *fftypes.Multipart
	SuccessStatus   int
	APIBaseURL      string
	ResponseHeaders http.Header
}

type FormParam

type FormParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
}

FormParam is a description of a multi-part form parameter

type PathParam

type PathParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// Default is the value that will be used in the case no value is supplied
	Default string
	// Example is a field to fill in, in the helper UI
	Example string
	// ExampleFromConf is a field to fill in, in the helper UI, from the runtime configuration
	ExampleFromConf config.RootKey
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
}

PathParam is a description of a path parameter

type QueryParam

type QueryParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// IsBool if this is a boolean query
	IsBool bool
	// Default is the value that will be used in the case no value is supplied
	Default string
	// Example is a field to fill in, in the helper UI
	Example string
	// ExampleFromConf is a field to fill in, in the helper UI, from the runtime configuration
	ExampleFromConf config.RootKey
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
	// Deprecated whether this param is deprecated
	Deprecated bool
}

QueryParam is a description of a path parameter

type Route

type Route struct {
	// Name is the operation name that will go into the Swagger definition, and prefix input/output schema
	Name string
	// Path is a Gorilla mux path spec
	Path string
	// PathParams is a list of documented path parameters
	PathParams []*PathParam
	// QueryParams is a list of documented query parameters
	QueryParams []*QueryParam
	// FormParams is a list of documented multi-part form parameters - combine with FormUploadHandler
	FormParams []*FormParam
	// FilterFactory is a reference to a filter object that defines the search param on resource collection interfaces
	FilterFactory database.QueryFactory
	// Method is the HTTP method
	Method string
	// Description is a message key to a translatable description of the operation
	Description i18n.MessageKey
	// JSONInputValue is a function that returns a pointer to a structure to take JSON input
	JSONInputValue func() interface{}
	// JSONInputMask are fields that aren't available for users to supply on input
	JSONInputMask []string
	// JSONInputSchema is a custom schema definition, for the case where the auto-gen + mask isn't good enough
	JSONInputSchema func(ctx context.Context) string
	// JSONOutputSchema is a custom schema definition, for the case where the auto-gen + mask isn't good enough
	JSONOutputSchema func(ctx context.Context) string
	// JSONOutputValue is a function that returns a pointer to a structure to take JSON output
	JSONOutputValue func() interface{}
	// JSONOutputCodes is the success response code
	JSONOutputCodes []int
	// JSONHandler is a function for handling JSON content type input. Input/Ouptut objects are returned by JSONInputValue/JSONOutputValue funcs
	JSONHandler func(r *APIRequest) (output interface{}, err error)
	// FormUploadHandler takes a single file upload, and returns a JSON object
	FormUploadHandler func(r *APIRequest) (output interface{}, err error)
	// Deprecated whether this route is deprecated
	Deprecated bool
}

Route defines each API operation on the REST API of Firefly Having a standard pluggable layer here on top of Gorilla allows us to autmoatically maintain the OpenAPI specification in-line with the code, while retaining the power of the Gorilla mux without a deep abstraction layer.

type SwaggerGenConfig

type SwaggerGenConfig struct {
	BaseURL                   string
	Title                     string
	Version                   string
	Description               string
	PanicOnMissingDescription bool
}