swagger

package
v0.0.0-...-93900ab Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2022 License: Apache-2.0 Imports: 11 Imported by: 3

Documentation

Overview

Package swagger ... Copyright 2017 Matt Ho

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package swagger ... Copyright 2017 Matt Ho

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package swagger ... Copyright 2017 Matt Ho

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package swagger ... Copyright 2017 Matt Ho

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package swagger ... Copyright 2017 Matt Ho

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

This section is empty.

Variables

View Source 
var UsePackageName = false

UsePackageName can be set to true to add package prefix of generated definition names

Functions

func RegisterCustomType 

func RegisterCustomType(v interface{}, p Property)

RegisterCustomType maps a reflect.Type to a pre-defined Property. This can be used to handle types that implement json.Marshaler or other interfaces. For example, a property with a Go type of time.Time would be represented as an object when it should be a string. 

RegisterCustomType(time.Time{}, Property{
  Type: "string",
  Format: "date-time",
})

Pointers to registered types will resolve to the same Property value unless that pointer type has also been registered as a custom type.

For example: registering time.Time will also apply to *time.Time, unless *time.Time has also been registered.

Types

type API 

type API struct {
	Swagger             string                 `json:"swagger,omitempty"`
	Info                Info                   `json:"info"`
	BasePath            string                 `json:"basePath,omitempty"`
	Schemes             []string               `json:"schemes,omitempty"`
	Paths               map[string]*Endpoints  `json:"paths,omitempty"`
	Definitions         map[string]Object      `json:"definitions,omitempty"`
	Tags                []Tag                  `json:"tags,omitempty"`
	Host                string                 `json:"host,omitempty"`
	SecurityDefinitions map[string]interface{} `json:"securityDefinitions,omitempty"`
	Security            *SecurityRequirement   `json:"security,omitempty"`
}

API provides the top level encapsulation for the swagger definition

func (*API) AddEndpoint 

func (a *API) AddEndpoint(e *Endpoint)

AddEndpoint adds the specified endpoint to the API definition; to generate an endpoint use ```endpoint.New```

func (*API) Handler 

func (a *API) Handler(enableCors bool) http.HandlerFunc

Handler is a factory method that generates an http.HandlerFunc; if enableCors is true, then the handler will generate cors headers

func (*API) RemovePrivate 

func (a *API) RemovePrivate() *API

RemovePrivate function removes 'private' (where name starts with "_") parameters

func (*API) RenderJSON 

func (a *API) RenderJSON() ([]byte, error)

RenderJSON returns the static swagger schema, as json

func (*API) Walk 

func (a *API) Walk(callback func(path string, endpoints *Endpoint))

Walk invoke the callback for each endpoints defined in the swagger doc

type Contact 

type Contact struct {
	Email string `json:"email,omitempty"`
}

Contact represents the contact entity from the swagger definition; used by Info

type Date 

type Date struct {
	time.Time
}

Date is used to store date without time

func (*Date) MarshalJSON 

func (d *Date) MarshalJSON() ([]byte, error)

MarshalJSON handler for Date type

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON handler for Date type

type Docs 

type Docs struct {
	Description string `json:"description"`
	URL         string `json:"url"`
}

Docs represents tag docs from the swagger definition

type Endpoint 

type Endpoint struct {
	Tags        []string            `json:"tags"`
	Path        string              `json:"-"`
	Method      string              `json:"-"`
	Summary     string              `json:"summary,omitempty"`
	Description string              `json:"description,omitempty"`
	OperationID string              `json:"operationId,omitempty"`
	Produces    []string            `json:"produces,omitempty"`
	Consumes    []string            `json:"consumes,omitempty"`
	Handler     interface{}         `json:"-"`
	Parameters  []Parameter         `json:"parameters,omitempty"`
	Responses   map[string]Response `json:"responses,omitempty"`
	Deprecated  bool                `json:"deprecated,omitempty"`

	// swagger spec requires security to be an array of objects
	Security *SecurityRequirement `json:"security,omitempty"`
}

Endpoint represents an endpoint from the swagger doc

type Endpoints 

type Endpoints struct {
	Delete  *Endpoint `json:"delete,omitempty"`
	Head    *Endpoint `json:"head,omitempty"`
	Get     *Endpoint `json:"get,omitempty"`
	Options *Endpoint `json:"options,omitempty"`
	Post    *Endpoint `json:"post,omitempty"`
	Put     *Endpoint `json:"put,omitempty"`
	Patch   *Endpoint `json:"patch,omitempty"`
	Trace   *Endpoint `json:"trace,omitempty"`
	Connect *Endpoint `json:"connect,omitempty"`
}

Endpoints represents all the swagger endpoints associated with a particular path

func (*Endpoints) ServeHTTP 

func (e *Endpoints) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP allows endpoints to serve itself using the builtin http mux

func (*Endpoints) Walk 

func (e *Endpoints) Walk(fn func(endpoint *Endpoint))

Walk calls the specified function for each method defined within the Endpoints

type GoogleSecurityScheme 

type GoogleSecurityScheme struct {
	SecurityScheme
	Issuer    string `json:"x-google-issuer,omitempty"`
	JwksURI   string `json:"x-google-jwks_uri,omitempty"`
	Audiences string `json:"x-google-audiences,omitempty"`
}

GoogleSecurityScheme represents a security scheme from the swagger definition for Google OAuth2

type GoogleSecuritySchemeOption 

type GoogleSecuritySchemeOption func(securityScheme *GoogleSecurityScheme)

GoogleSecuritySchemeOption provides additional customizations to the GoogleSecurityScheme. See https://cloud.google.com/endpoints/docs/openapi/openapi-extensions for more details.

func GoogleEndpointsSecurity 

func GoogleEndpointsSecurity(issuer, jwksURI, audiences string) GoogleSecuritySchemeOption

GoogleEndpointsSecurity defines a security scheme for Google OAuth2 authentication. See https://cloud.google.com/endpoints/docs/openapi/openapi-extensions for more details.

func GoogleOAuth2Security 

func GoogleOAuth2Security(flow, authorizationURL, tokenURL, issuer, jwksURI, audiences string) GoogleSecuritySchemeOption

GoogleOAuth2Security defines a security scheme for Google OAuth2 authentication. See https://cloud.google.com/endpoints/docs/openapi/openapi-extensions for more details. 

type Header struct {
	Type        string `json:"type"`
	Format      string `json:"format,omitempty"`
	Description string `json:"description,omitempty"`
}

Header represents a response header

type Info 

type Info struct {
	Description    string   `json:"description,omitempty"`
	Version        string   `json:"version,omitempty"`
	TermsOfService string   `json:"termsOfService,omitempty"`
	Title          string   `json:"title,omitempty"`
	Contact        *Contact `json:"contact,omitempty"`
	License        *License `json:"license,omitempty"`
}

Info represents the info entity from the swagger definition

type Items 

type Items struct {
	Type                 string      `json:"type,omitempty"`
	Default              interface{} `json:"default,omitempty"`
	Format               string      `json:"format,omitempty"`
	Enum                 []string    `json:"enum,omitempty"`
	Ref                  string      `json:"$ref,omitempty"`
	MinItems             int         `json:"minItems,omitempty"`
	MaxItems             int         `json:"maxItems,omitempty"`
	UniqueItems          bool        `json:"uniqueItems,omitempty"`
	MinLength            int         `json:"minLength,omitempty"`
	MaxLength            int         `json:"maxLength,omitempty"`
	Minimum              *int64      `json:"minimum,omitempty"`
	Maximum              *int64      `json:"maximum,omitempty"`
	ExclusiveMinimum     bool        `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool        `json:"exclusiveMaximum,omitempty"`
	Pattern              string      `json:"pattern,omitempty"`
	AdditionalProperties interface{} `json:"additionalProperties,omitempty"`
}

Items represents items from the swagger doc

type License 

type License struct {
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

License represents the license entity from the swagger definition; used by Info

type Object 

type Object struct {
	IsArray              bool                `json:"-"`
	GoType               reflect.Type        `json:"-"`
	Name                 string              `json:"-"`
	Type                 string              `json:"type"`
	Default              interface{}         `json:"default,omitempty"`
	Format               string              `json:"format,omitempty"`
	Required             []string            `json:"required,omitempty"`
	Properties           map[string]Property `json:"properties,omitempty"`
	AdditionalProperties bool                `json:"additionalProperties"`
}

Object represents the object entity from the swagger definition

type Parameter 

type Parameter struct {
	In                   string      `json:"in,omitempty"`
	Name                 string      `json:"name,omitempty"`
	Description          string      `json:"description,omitempty"`
	Required             bool        `json:"required"`
	Schema               *Schema     `json:"schema,omitempty"`
	Type                 string      `json:"type,omitempty"`
	Items                *Items      `json:"items,omitempty"`
	Default              interface{} `json:"default,omitempty"`
	Format               string      `json:"format,omitempty"`
	Enum                 []string    `json:"enum,omitempty"`
	Nullable             bool        `json:"x-nullable,omitempty"`
	Pattern              string      `json:"pattern,omitempty"`
	MinItems             int         `json:"minItems,omitempty"`
	MaxItems             int         `json:"maxItems,omitempty"`
	UniqueItems          bool        `json:"uniqueItems,omitempty"`
	MaxLength            int         `json:"maxLength,omitempty"`
	MinLength            int         `json:"minLength,omitempty"`
	Minimum              *int64      `json:"minimum,omitempty"`
	Maximum              *int64      `json:"maximum,omitempty"`
	ExclusiveMinimum     bool        `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool        `json:"exclusiveMaximum,omitempty"`
	AdditionalProperties interface{} `json:"additionalProperties,omitempty"`
}

Parameter represents a parameter from the swagger doc

type Property 

type Property struct {
	GoType               reflect.Type `json:"-"`
	Type                 string       `json:"type,omitempty"`
	Description          string       `json:"description,omitempty"`
	Enum                 []string     `json:"enum,omitempty"`
	Default              interface{}  `json:"default,omitempty"`
	Format               string       `json:"format,omitempty"`
	Pattern              string       `json:"pattern,omitempty"`
	Ref                  string       `json:"$ref,omitempty"`
	Example              string       `json:"example,omitempty"`
	Items                *Items       `json:"items,omitempty"`
	Nullable             bool         `json:"x-nullable,omitempty"`
	MinItems             int          `json:"minItems,omitempty"`
	MaxItems             int          `json:"maxItems,omitempty"`
	UniqueItems          bool         `json:"uniqueItems,omitempty"`
	MinLength            int          `json:"minLength,omitempty"`
	MaxLength            int          `json:"maxLength,omitempty"`
	Minimum              *int64       `json:"minimum,omitempty"`
	Maximum              *int64       `json:"maximum,omitempty"`
	ExclusiveMinimum     bool         `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool         `json:"exclusiveMaximum,omitempty"`
	AdditionalProperties interface{}  `json:"additionalProperties,omitempty"`
}

Property represents the property entity from the swagger definition

type Response 

type Response struct {
	Description string            `json:"description,omitempty"`
	Schema      *Schema           `json:"schema,omitempty"`
	Headers     map[string]Header `json:"headers,omitempty"`
}

Response represents a response from the swagger doc

type Schema 

type Schema struct {
	Type      string      `json:"type,omitempty"`
	Items     *Items      `json:"items,omitempty"`
	Ref       string      `json:"$ref,omitempty"`
	Prototype interface{} `json:"-"`
}

Schema represents a schema from the swagger doc

func MakeSchema 

func MakeSchema(prototype interface{}) *Schema

MakeSchema takes struct or pointer to a struct and returns a Schema instance suitable for use by the swagger doc

type SecurityRequirement 

type SecurityRequirement struct {
	Requirements    []map[string][]string
	DisableSecurity bool
}

SecurityRequirement represents a security requirement from the swagger doc

func (*SecurityRequirement) MarshalJSON 

func (s *SecurityRequirement) MarshalJSON() ([]byte, error)

MarshalJSON serializes a SecurityRequirement

type SecurityScheme 

type SecurityScheme struct {
	Type             string            `json:"type"`
	Description      string            `json:"description,omitempty"`
	Name             string            `json:"name,omitempty"`
	In               string            `json:"in,omitempty"`
	Flow             string            `json:"flow,omitempty"`
	AuthorizationURL string            `json:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty"`
	Scopes           map[string]string `json:"scopes,omitempty"`
}

SecurityScheme represents a security scheme from the swagger definition.

type SecuritySchemeOption 

type SecuritySchemeOption func(securityScheme *SecurityScheme)

SecuritySchemeOption provides additional customizations to the SecurityScheme.

func APIKeySecurity 

func APIKeySecurity(name, in string) SecuritySchemeOption

APIKeySecurity defines a security scheme for API key authentication. "in" is the location of the API key (query or header). "name" is the name of the header or query parameter to be used.

func BasicSecurity 

func BasicSecurity() SecuritySchemeOption

BasicSecurity defines a security scheme for HTTP Basic authentication.

func OAuth2Scope 

func OAuth2Scope(scope, description string) SecuritySchemeOption

OAuth2Scope adds a new scope to the security scheme.

func OAuth2Security 

func OAuth2Security(flow, authorizationURL, tokenURL string) SecuritySchemeOption

OAuth2Security defines a security scheme for OAuth2 authentication. Flow can be one of implicit, password, application, or accessCode.

func SecuritySchemeDescription 

func SecuritySchemeDescription(description string) SecuritySchemeOption

SecuritySchemeDescription sets the security scheme's description.

type Tag 

type Tag struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Docs        Docs   `json:"externalDocs"`
}

Tag represents a swagger tag

type Time 

type Time struct {
	time.Time
}

Time is used to store time without date

func (*Time) MarshalJSON 

func (t *Time) MarshalJSON() ([]byte, error)

MarshalJSON handler for Time type

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON handler for Time type

type UUID 

type UUID string

UUID is used to store UUID values

Source Files

View all Source files

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.