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
- type HandlerDoc
- type Refs
- type RouteConverter
- type RuleConverter
- type UIOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
SchemaFromField convert a validation.Field to OpenAPI Schema.
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 ¶
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 ¶
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.
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 ¶
RuleConverter sets a schema's fields to values matching the given validation rule, if supported.
type UIOptions ¶ added in v0.0.2
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 ¶ added in v0.0.2
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.
Source Files