common

Documentation

Index

• func EscapeJSONPointer(p string) string
• func GetOpenAPITypeFormat(typeName string) (string, string)
• type Config
• type GetOpenAPIDefinitions
• type OpenAPIDefinition
• type OpenAPIDefinitionGetter
• type ReferenceCallback

Functions

func EscapeJSONPointer

func EscapeJSONPointer(p string) string

EscapeJSONPointer encode json pointer by rfc6901

func GetOpenAPITypeFormat

func GetOpenAPITypeFormat(typeName string) (string, string)

GetOpenAPITypeFormat is a reference for converting go (or any custom type) to a simple open API type,format pair. There are two ways to customize spec for a type. If you add it here, a type will be converted to a simple type and the type comment (the comment that is added before type definition) will be lost. The spec will still have the property comment. The second way is to implement OpenAPIDefinitionGetter interface. That function can customize the spec (so the spec does not need to be simple type,format) or can even return a simple type,format (e.g. IntOrString). For simple type formats, the benefit of adding OpenAPIDefinitionGetter interface is to keep both type and property documentation. Example:

type Sample struct {
     ...
     // port of the server
     port IntOrString
     ...
}

// IntOrString documentation... type IntOrString { ... }

Adding IntOrString to this function:

"port" : {
          format:      "string",
          type:        "int-or-string",
          Description: "port of the server"
}

Implement OpenAPIDefinitionGetter for IntOrString:

"port" : {
          $Ref:    "#/definitions/IntOrString"
          Description: "port of the server"
}

... definitions:

{
          "IntOrString": {
                    format:      "string",
                    type:        "int-or-string",
                    Description: "IntOrString documentation..."    // new
          }
}

Types

type Config

type Config struct {

	// Info is general information about the API.
	// TODO(liubog2008): it should be generated from comments
	Info *spec.Info

	// OpenAPIDefinitions should provide definition for all models used by routes. Failure to provide this map
	// or any of the models will result in spec generation failure.
	GetDefinitions GetOpenAPIDefinitions

	// GetDefinitionName returns a friendly name for a definition base on the serving path. parameter `name` is the full name of the definition.
	// It is an optional function to customize model names.
	GetDefinitionName func(name string) (string, spec.Extensions)
}

Config is set of configuration for openAPI spec generation.

type GetOpenAPIDefinitions

type GetOpenAPIDefinitions func(ReferenceCallback) map[string]OpenAPIDefinition

GetOpenAPIDefinitions is collection of all definitions.

type OpenAPIDefinition

type OpenAPIDefinition struct {
	Schema       spec.Schema
	Dependencies []string
}

OpenAPIDefinition describes single type. Normally these definitions are auto-generated using gen-openapi.

type OpenAPIDefinitionGetter

type OpenAPIDefinitionGetter interface {
	OpenAPIDefinition() *OpenAPIDefinition
}

OpenAPIDefinitionGetter gets openAPI definitions for a given type. If a type implements this interface, the definition returned by it will be used, otherwise the auto-generated definitions will be used. See GetOpenAPITypeFormat for more information about trade-offs of using this interface or GetOpenAPITypeFormat method when possible.

type ReferenceCallback

type ReferenceCallback func(path string) spec.Ref

ReferenceCallback is defined to get ref from path