go-openapi

go-openapi

Yet another take at handling OpenAPI specifications from Go - specifically this tooling is aimed at compile time generation of OpenAPI specification documents based on REST endpoint written in Go.

The tool is based on a mix of godoc directives and information derived from go structs and simple types. The godoc directives handles metadata that cannot be derived directly from the source code.

An example can be found in the fixture directory.

Usage

Install the tool running the following command line:

go install github.com/neticdk/go-openapi/cmd/openapi@latest

The tool comes with two commands: generate and expand

Generate OpenAPI Specification

To generate the OpenAPI Specification run generate. The below will generate an OpenAPI Specification document to standard out based on the example in the fixture directory.

openapi generate -o- ./pkg/generator/fixture/...

Expand OpenAPI Specification

The tool also supports inlining JSON schema definitions in the OpenAPI Specification. This can be useful for other tools that iterate through the specification because they do not have to resolve the references then. The below will inline the references in the give OpenAPI Specification document and return the result on standard out.

openapi expand -o- openapi.json

JSON Schema directives

The following directives can be used on fields in a Go struct types to indicate how these should be included for JSON Schema rendering. The directives for JSON Schema can be used with both schema: or openapi: prefixes although the below table shows the schema: prefix. All these directive take exactly one parameter.

The below is an example of a annotated Go struct.

// Model is a fixture for rendering models
//
//openapi:component schema Model
type Model struct {
  fixture.CommonType
  embeddedPrivate

  // Field1 description
  //schema:example mystring
  //schema:default def
  Field1 string `json:"field1"`

  //openapi:format uri
  Field2 int `json:"field2"`
  Field3 float32
  Field4 time.Time         `json:"timestamp"`
  Field5 *refPrivat        `json:"field5"`
  Field6 RefExported       `json:"field6"`
  Field7 []string          `json:"field7"`
  Field8 map[string]string `json:"field8"`
}

OpenAPI directives

The following directives support providing metadata for specifically rendering the OpenAPI Specification document.

The below is an exmple of specifying general information for the generated OpenAPI Specification document.

// Package fixture Fixture Demo API
//
// The package (and subpackage) provides test fixture and illustrates the use of the godoc directives
//
//openapi:info 1.0.0
package fixture

The below is an example of using the directives for a number of REST endpoints.

package api

// ListOperation lists the entities
//
//openapi:operation /entities GET
//openapi:tag tag1
//openapi:tag tag2
func ListOperation() {}

// GetOperation gets a specific entity
//
//openapi:operation /entities/{id} GET
//openapi:parameter id path string "the id of the entity"
//openapi:response default "this is a description"
//openapi:responseContent default application/json Model
//openapi:responseHeader default My-Custom-Header string "this header will tell you..."
//openapi:responseHeader default My-Other-Custom-Header string/date-time "this header will tell you..."
//openapi:responseExample default application/ld+json examples/get_operation_default.json
//openapi:response 400 "client did something wrong"
//openapi:responseContent 400 application/problem+json Problem
//openapi:responseExample 400 application/problem+json examples/get_operation_error.json
//openapi:response 404 "something was not found"
//openapi:responseContent 404 application/problem+json Problem
func GetOperation() {}

// ReplaceOperation will replace (or create) a specific entity
//
//openapi:operation /entities/{id} PUT
//openapi:parameter id path string "the id of the entity"
//openapi:requestBody application/json Model "The data to replace the current entity - if any"
func ReplaceOperation() {}