Categorygoyave.dev/openapi3
modulepackage
0.3.0
Repository: https://github.com/go-goyave/openapi3.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
23
Dependents
0
Files
950 SLOC

# README

openapi3 - Automatic spec generator for Goyave

Version Build Status Coverage Status Go Reference

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/[email protected]

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)

# Functions

ConvertToBody convert validation.Rules to OpenAPI RequestBody.
ConvertToQuery convert validation.Rules to OpenAPI query Parameters.
Has returns true if the given set of rules contains at least one rule having the given name, ignoring fields inside objects.
HasFile returns true if the given set of rules contains at least one "file" rule, ignoring fields inside objects.
HasOnlyOptionalFiles returns true if the given set of rules doesn't contain any required "file" rule.
HasRequired returns true if the given set of rules contains at least one "required" rule, ignoring fields inside objects.
NewGenerator create a new OpenAPI 3 specification Generator.
NewRefs create a new Refs struct with initialized maps.
NewRouteConverter create a new RouteConverter using the given Route as input.
NewUIOptions create a new UIOption struct with default values.
RegisterRuleConverter register a RuleConverter function for the rule identified by the given ruleName.
SchemaFromField convert a validation.Field to OpenAPI Schema.
Serve register the SwaggerUI route on the given router, with the given uri, and using the given UIOptions.

# Structs

Generator for OpenAPI 3 specification based on Router.
HandlerDoc info extracted from AST about a Handler.
Refs cache structure associating validation rules pointers to OpenAPI refs to avoid generating them multiple times and allow the use of OpenAPI components.
RouteConverter converts goyave.Route to OpenAPI operations.
UIOptions options for the SwaggerUI Handler.

# Type aliases

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