openapi3

README

openapi3 - Automatic spec generator for Goyave

An automated OpenAPI 3 specification generator for the Goyave REST API framework, using kin-openapi/openapi3 in the background.

Just from reading your code, this generator is able to fill an OpenAPI 3 specification with:

• Paths and operations
• Path parameters (with patterns)
• Body and query parameters
• Full support for validation
• File upload support
• Handler documentation (uses comments on Handler function)
• Server (uses config for domain name / host / port)
• SwaggerUI

Note: this generator doesn't create responses because it doesn't have any way to know what your handlers will return.

Usage

go get -u goyave.dev/openapi3

If you are using Goyave v3: go get -u goyave.dev/openapi3@v0.1.0

Add the following at the end of your main route registrer:

spec := openapi3.NewGenerator().Generate(router)
json, err := spec.MarshalJSON()
if err != nil {
    panic(err)
}
fmt.Println(string(json))

You can alter the resulting openapi3.T after generation. Like so, you can add responses details to your operations, top-level info, and more.

SwaggerUI

You can serve a SwaggerUI for your spec directly from your server using the built-in handler:

spec := openapi3.NewGenerator().Generate(router)
opts := openapi3.NewUIOptions(spec)
openapi3.Serve(router, "/openapi", opts)

Then navigate to http://localhost:8080/openapi (provided you use the default port).

License

This package is MIT Licensed. Copyright (c) 2021 Jérémy LAMBERT (SystemGlitch)

Documentation

Index

• func ConvertToBody(rules *validation.Rules) *openapi3.RequestBodyRef
• func ConvertToQuery(rules *validation.Rules) []*openapi3.ParameterRef
• func Has(rules *validation.Rules, ruleName string) bool
• func HasFile(rules *validation.Rules) bool
• func HasOnlyOptionalFiles(rules *validation.Rules) bool
• func HasRequired(rules *validation.Rules) bool
• func RegisterRuleConverter(ruleName string, converter RuleConverter)
• func SchemaFromField(field *validation.Field) (*openapi3.Schema, *openapi3.Encoding)
• func Serve(router *goyave.Router, uri string, opts *UIOptions)
• type Generator
  • func NewGenerator() *Generator
  • func (g *Generator) Generate(router *goyave.Router) *openapi3.T
• type HandlerDoc
• type Refs
  • func NewRefs() *Refs
• type RouteConverter
  • func NewRouteConverter(route *goyave.Route, refs *Refs) *RouteConverter
  • func (c *RouteConverter) Convert(spec *openapi3.T)
• type RuleConverter
• type UIOptions
  • func NewUIOptions(spec *openapi3.T) *UIOptions

Functions

func ConvertToBody

func ConvertToBody(rules *validation.Rules) *openapi3.RequestBodyRef

ConvertToBody convert validation.Rules to OpenAPI RequestBody.

func ConvertToQuery

func ConvertToQuery(rules *validation.Rules) []*openapi3.ParameterRef

ConvertToQuery convert validation.Rules to OpenAPI query Parameters.

func Has

func Has(rules *validation.Rules, ruleName string) bool

Has returns true if the given set of rules contains at least one rule having the given name, ignoring fields inside objects.

func HasFile

func HasFile(rules *validation.Rules) bool

HasFile returns true if the given set of rules contains at least one "file" rule, ignoring fields inside objects.

func HasOnlyOptionalFiles

func HasOnlyOptionalFiles(rules *validation.Rules) bool

HasOnlyOptionalFiles returns true if the given set of rules doesn't contain any required "file" rule.

func HasRequired

func HasRequired(rules *validation.Rules) bool

HasRequired returns true if the given set of rules contains at least one "required" rule, ignoring fields inside objects.

func RegisterRuleConverter

func RegisterRuleConverter(ruleName string, converter RuleConverter)

RegisterRuleConverter register a RuleConverter function for the rule identified by the given ruleName. Registering a rule converter allows to handle custom rules.

func SchemaFromField

func SchemaFromField(field *validation.Field) (*openapi3.Schema, *openapi3.Encoding)

SchemaFromField convert a validation.Field to OpenAPI Schema.

func Serve

func Serve(router *goyave.Router, uri string, opts *UIOptions)

Serve register the SwaggerUI route on the given router, with the given uri, and using the given UIOptions.

Types

type Generator

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

Generator for OpenAPI 3 specification based on Router.

func NewGenerator

func NewGenerator() *Generator

NewGenerator create a new OpenAPI 3 specification Generator.

func (*Generator) Generate

func (g *Generator) Generate(router *goyave.Router) *openapi3.T

Generate an OpenAPI 3 specification based on the given Router.

Goyave config will be loaded (if not already).

The Info section is pre-filled with version 0.0.0 and the app name, fetched from the config. Servers section will be filled using the configuration as well, thanks to the goyave.BaseURL() function.

type HandlerDoc

type HandlerDoc struct {
	FuncName    string
	Description string
}

HandlerDoc info extracted from AST about a Handler.

type Refs

type Refs struct {
	Schemas         map[*validation.Rules]*openapi3.SchemaRef
	ParamSchemas    map[string]*openapi3.SchemaRef
	Parameters      map[string]*openapi3.ParameterRef
	QueryParameters map[*validation.Rules][]*openapi3.ParameterRef
	RequestBodies   map[*validation.Rules]*openapi3.RequestBodyRef
	AST             map[string]*ast.File
	HandlerDocs     map[uintptr]*HandlerDoc
}

Refs cache structure associating validation rules pointers to OpenAPI refs to avoid generating them multiple times and allow the use of OpenAPI components.

func NewRefs

func NewRefs() *Refs

NewRefs create a new Refs struct with initialized maps.

type RouteConverter

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

RouteConverter converts goyave.Route to OpenAPI operations.

func NewRouteConverter

func NewRouteConverter(route *goyave.Route, refs *Refs) *RouteConverter

NewRouteConverter create a new RouteConverter using the given Route as input. The converter will use and fill the given Refs.

func (*RouteConverter) Convert

func (c *RouteConverter) Convert(spec *openapi3.T)

Convert route to OpenAPI operations and adds the results to the given spec.

type RuleConverter

type RuleConverter func(r *validation.Rule, s *openapi3.Schema, encoding *openapi3.Encoding)

RuleConverter sets a schema's fields to values matching the given validation rule, if supported.

type UIOptions

type UIOptions struct {

	// Title the title of the SwaggerUI HTML document
	Title string

	// Favicon32 URL to a 32x32 PNG favicon
	Favicon32 string
	// Favicon32 URL to a 16x16 PNG favicon
	Favicon16 string

	// BundleURL URL to the SwaggerUI js bundle
	BundleURL string
	// BundleURL URL to the SwaggerUI standalone preset js bundle
	PresetURL string
	// StylesURL URL to the SwaggerUI CSS
	StylesURL string

	// Spec JSON object
	Spec string
}

UIOptions options for the SwaggerUI Handler.

func NewUIOptions

func NewUIOptions(spec *openapi3.T) *UIOptions

NewUIOptions create a new UIOption struct with default values.

By default, favicons, swagger-ui js and css use official latest available versions from the unpkg.com CDN.

The given spec can be `nil`, in which case, you'll have to set the returned struct's `Spec` field to a valid JSON string.