/openapi3

Automatic OpenAPI 3 spec generator for the Goyave framework

Primary LanguageGoMIT LicenseMIT

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/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)