common

package
v0.0.0-...-2c72e55 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 12, 2024 License: Apache-2.0 Imports: 5 Imported by: 1,821

Documentation

Overview

package common holds shared code and types between open API code generator and spec generator.

Index

Constants

View Source 
const (
	// TODO: Make this configurable.
	ExtensionPrefix   = "x-kubernetes-"
	ExtensionV2Schema = ExtensionPrefix + "v2-schema"
)
View Source 
const (
	// PathParameterKind indicates the request parameter type is "path".
	PathParameterKind = ParameterKind(iota)

	// QueryParameterKind indicates the request parameter type is "query".
	QueryParameterKind

	// BodyParameterKind indicates the request parameter type is "body".
	BodyParameterKind

	// HeaderParameterKind indicates the request parameter type is "header".
	HeaderParameterKind

	// FormParameterKind indicates the request parameter type is "form".
	FormParameterKind

	// UnknownParameterKind indicates the request parameter type has not been specified.
	UnknownParameterKind
)

Variables

This section is empty.

Functions

func EscapeJsonPointer 

func EscapeJsonPointer(p string) string

func GenerateOpenAPIV3OneOfSchema 

func GenerateOpenAPIV3OneOfSchema(types []string) (oneOf []spec.Schema)

GenerateOpenAPIV3OneOfSchema generate the set of schemas that MUST be assigned to SchemaProps.OneOf

func OpenAPITypeFormat 

func OpenAPITypeFormat(typeName string) (string, string)

This function 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
          }
}

func OpenAPIZeroValue 

func OpenAPIZeroValue(typeName string) (interface{}, bool)

Returns the zero-value for the given type along with true if the type could be found.

Types

type Config 

type Config struct {
	// List of supported protocols such as https, http, etc.
	ProtocolList []string

	// Info is general information about the API.
	Info *spec.Info

	// DefaultResponse will be used if an operation does not have any responses listed. It
	// will show up as ... "responses" : {"default" : $DefaultResponse} in the spec.
	DefaultResponse *spec.Response

	// ResponseDefinitions will be added to "responses" under the top-level swagger object. This is an object
	// that holds responses definitions that can be used across operations. This property does not define
	// global responses for all operations. For more info please refer:
	//     https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields
	ResponseDefinitions map[string]spec.Response

	// CommonResponses will be added as a response to all operation specs. This is a good place to add common
	// responses such as authorization failed.
	CommonResponses map[int]spec.Response

	// List of webservice's path prefixes to ignore
	IgnorePrefixes []string

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

	// Provides the definition for all models used by routes. One of GetDefinitions or Definitions must be defined to generate a spec.
	// This takes precedent over the GetDefinitions function
	Definitions map[string]OpenAPIDefinition

	// GetOperationIDAndTags returns operation id and tags for a restful route. It is an optional function to customize operation IDs.
	//
	// Deprecated: GetOperationIDAndTagsFromRoute should be used instead. This cannot be specified if using the new Route
	// interface set of funcs.
	GetOperationIDAndTags func(r *restful.Route) (string, []string, error)

	// GetOperationIDAndTagsFromRoute returns operation id and tags for a Route. It is an optional function to customize operation IDs.
	GetOperationIDAndTagsFromRoute func(r Route) (string, []string, error)

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

	// PostProcessSpec runs after the spec is ready to serve. It allows a final modification to the spec before serving.
	PostProcessSpec func(*spec.Swagger) (*spec.Swagger, error)

	// SecurityDefinitions is list of all security definitions for OpenAPI service. If this is not nil, the user of config
	// is responsible to provide DefaultSecurity and (maybe) add unauthorized response to CommonResponses.
	SecurityDefinitions *spec.SecurityDefinitions

	// DefaultSecurity for all operations. This will pass as spec.SwaggerProps.Security to OpenAPI.
	// For most cases, this will be list of acceptable definitions in SecurityDefinitions.
	DefaultSecurity []map[string][]string
}

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.

func EmbedOpenAPIDefinitionIntoV2Extension 

func EmbedOpenAPIDefinitionIntoV2Extension(main OpenAPIDefinition, embedded OpenAPIDefinition) OpenAPIDefinition

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 OpenAPIV3Config 

type OpenAPIV3Config struct {
	// Info is general information about the API.
	Info *spec.Info

	// DefaultResponse will be used if an operation does not have any responses listed. It
	// will show up as ... "responses" : {"default" : $DefaultResponse} in the spec.
	DefaultResponse *spec3.Response

	// ResponseDefinitions will be added to responses component. This is an object
	// that holds responses that can be used across operations.
	ResponseDefinitions map[string]*spec3.Response

	// CommonResponses will be added as a response to all operation specs. This is a good place to add common
	// responses such as authorization failed.
	CommonResponses map[int]*spec3.Response

	// List of webservice's path prefixes to ignore
	IgnorePrefixes []string

	// 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.
	// One of GetDefinitions or Definitions must be defined to generate a spec.
	GetDefinitions GetOpenAPIDefinitions

	// Provides the definition for all models used by routes. One of GetDefinitions or Definitions must be defined to generate a spec.
	// This takes precedent over the GetDefinitions function
	Definitions map[string]OpenAPIDefinition

	// GetOperationIDAndTags returns operation id and tags for a restful route. It is an optional function to customize operation IDs.
	//
	// Deprecated: GetOperationIDAndTagsFromRoute should be used instead. This cannot be specified if using the new Route
	// interface set of funcs.
	GetOperationIDAndTags func(r *restful.Route) (string, []string, error)

	// GetOperationIDAndTagsFromRoute returns operation id and tags for a Route. It is an optional function to customize operation IDs.
	GetOperationIDAndTagsFromRoute func(r Route) (string, []string, error)

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

	// PostProcessSpec runs after the spec is ready to serve. It allows a final modification to the spec before serving.
	PostProcessSpec func(*spec3.OpenAPI) (*spec3.OpenAPI, error)

	// SecuritySchemes is list of all security schemes for OpenAPI service.
	SecuritySchemes spec3.SecuritySchemes

	// DefaultSecurity for all operations.
	DefaultSecurity []map[string][]string
}

OpenAPIV3Config is set of configuration for OpenAPI V3 spec generation.

type OpenAPIV3DefinitionGetter 

type OpenAPIV3DefinitionGetter interface {
	OpenAPIV3Definition() *OpenAPIDefinition
}

type Parameter 

type Parameter interface {
	// Name defines the unique-per-route identifier.
	Name() string
	// Description is the human-readable description of the param.
	Description() string
	// Required defines if this parameter must be provided.
	Required() bool
	// Kind defines the type of the parameter itself.
	Kind() ParameterKind
	// DataType defines the type of data the parameter carries.
	DataType() string
	// AllowMultiple defines if more than one value can be supplied for the parameter.
	AllowMultiple() bool
}

Parameter is a Route parameter.

type ParameterKind 

type ParameterKind int

ParameterKind is an enum of route parameter types.

type PathHandler 

type PathHandler interface {
	Handle(path string, handler http.Handler)
}

type PathHandlerByGroupVersion 

type PathHandlerByGroupVersion interface {
	Handle(path string, handler http.Handler)
	HandlePrefix(path string, handler http.Handler)
}

type ReferenceCallback 

type ReferenceCallback func(path string) spec.Ref

type Route 

type Route interface {
	// Method defines the HTTP Method.
	Method() string
	// Path defines the route's endpoint.
	Path() string
	// OperationName defines a machine-readable ID for the route.
	OperationName() string
	// Parameters defines the list of accepted parameters.
	Parameters() []Parameter
	// Description is a human-readable route description.
	Description() string
	// Consumes defines the consumed content-types.
	Consumes() []string
	// Produces defines the produced content-types.
	Produces() []string
	// Metadata allows adding extensions to the generated spec.
	Metadata() map[string]interface{}
	// RequestPayloadSample defines an example request payload. Can return nil.
	RequestPayloadSample() interface{}
	// ResponsePayloadSample defines an example response payload. Can return nil.
	ResponsePayloadSample() interface{}
	// StatusCodeResponses defines a mapping of HTTP Status Codes to the specific response(s).
	// Multiple responses with the same HTTP Status Code are acceptable.
	StatusCodeResponses() []StatusCodeResponse
}

Route is a logical endpoint of a service.

type RouteContainer 

type RouteContainer interface {
	// RootPath is the path that all contained routes are nested under.
	RootPath() string
	// PathParameters are common parameters defined in the root path.
	PathParameters() []Parameter
	// Routes are all routes exposed under the root path.
	Routes() []Route
}

RouteContainer is the entrypoint for a service, which may contain multiple routes under a common path with a common set of path parameters.

type StatusCodeResponse 

type StatusCodeResponse interface {
	// Code defines the HTTP Status Code.
	Code() int
	// Message returns the human-readable message.
	Message() string
	// Model defines an example payload for this response.
	Model() interface{}
}

StatusCodeResponse is an explicit response type with an HTTP Status Code.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.