openapix

README

go-openapix

go-openapix provides some useful convience functions to to swaggest, so that you can build up your APIs in a type-checked and auto-documented way!

Some highlights:

• MustCreateOpenapiEndpoint - uses generics to enforce that you are returning the correct (documented) type in code. End-user does not need to use generics themselves, making it simpler to use. It also generates a endpoint name, based on the title you provide - no accidental copy/paste doubling-up endpoints with the same name.
• MustCheckNonNullArrays - document [] instead of null when the array is empty.

Usage:

func main() {
	apiSchema := &openapi.Collector{}
	r := chirouter.NewWrapper(chi.NewRouter())

	r.Use(nethttp.OpenAPIMiddleware(apiSchema))

	... // your setup here

	// add an endpoint
	openapix.Post(r, "/customers", GetAllCustomers(dbConnection, customersStore))

	// check array types are marked as non-null; i.e. no items will return "[]" instead of "null"
   	openapix.MustCheckNonNullArrays(apiSchema.Reflector().Spec.Components.Schemas.MapOfSchemaOrRefValues)

	openapix.MustNotHaveDuplicateOperationIDOrUnknownSecurity(apiSchema.Reflector().Spec)

	// start your web server
}

type GetAllCustomersRequest struct{}

type GetAllCustomersResponse struct {
	Customers []Customer `json:"customers" nullable:"false"`
}

func GetAllCustomers(dbConnection *sql.DB, customersStore *CustomersStore) *nethttp.Handler {
	return openapix.MustCreateOpenapiEndpoint(
		"Get All Customers",
		&openapix.HandlerOptions{Tags: []string{"Customers"}},
		func(ctx context.Context, input *GetAllCustomersRequest, output *GetAllCustomersResponse) error {
			customers, err := customersStore.GetAll(dbConnection)
			if err != nil {
				return status.Wrap(err, status.Internal)
			}

			output.Customers = customers

			return nil
		},
	)
}

Documentation

Index

• func Connect(r router, path string, handler *nethttp.Handler)
• func Delete(r router, path string, handler *nethttp.Handler)
• func Get(r router, path string, handler *nethttp.Handler)
• func Head(r router, path string, handler *nethttp.Handler)
• func MustCheckNonNullArrays(definitionMap map[string]openapi3.SchemaOrRef)
• func MustCreateOpenapiEndpoint[Req any, Resp any](title string, opts *HandlerOptions, handler OpenapiHandlerFunc[Req, Resp]) *nethttp.Handler
• func MustNotHaveDuplicateOperationIDOrUnknownSecurity(spec *openapi3.Spec)
• func Options(r router, path string, handler *nethttp.Handler)
• func Patch(r router, path string, handler *nethttp.Handler)
• func Post(r router, path string, handler *nethttp.Handler)
• func Put(r router, path string, handler *nethttp.Handler)
• func Trace(r router, path string, handler *nethttp.Handler)
• type HandlerOptions
• type HandlerSecurity
• type OpenapiHandlerFunc

Functions

func Connect

func Connect(r router, path string, handler *nethttp.Handler)

func Delete

func Delete(r router, path string, handler *nethttp.Handler)

func Get

func Get(r router, path string, handler *nethttp.Handler)

func Head

func Head(r router, path string, handler *nethttp.Handler)

func MustCheckNonNullArrays

func MustCheckNonNullArrays(definitionMap map[string]openapi3.SchemaOrRef)

MustCheckNonNullArrays enforces non-null arrays across the whole of your schema. Use if desired on your particular schema; this isn't suitable for all schemas.

func MustCreateOpenapiEndpoint

func MustCreateOpenapiEndpoint[Req any, Resp any](title string, opts *HandlerOptions, handler OpenapiHandlerFunc[Req, Resp]) *nethttp.Handler

MustCreateOpenapiEndpoint creates an openapi endpoint. It panics on error.

func MustNotHaveDuplicateOperationIDOrUnknownSecurity

func MustNotHaveDuplicateOperationIDOrUnknownSecurity(spec *openapi3.Spec)

func Options

func Options(r router, path string, handler *nethttp.Handler)

func Patch

func Patch(r router, path string, handler *nethttp.Handler)

func Post

func Post(r router, path string, handler *nethttp.Handler)

func Put

func Put(r router, path string, handler *nethttp.Handler)

func Trace

func Trace(r router, path string, handler *nethttp.Handler)

Types

type HandlerOptions

type HandlerOptions struct {
	Tags     []string
	Security *HandlerSecurity
}

type HandlerSecurity

type HandlerSecurity struct {
	SecurityName string
	Scopes       []string
}

type OpenapiHandlerFunc

type OpenapiHandlerFunc[Req any, Resp any] func(ctx context.Context, input *Req, output *Resp) error