swagger

Documentation

Overview

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.

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.

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.

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.

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

• type API
  • func (a *API) AddEndpoint(e *Endpoint)
  • func (a *API) Handler(enableCors bool) http.HandlerFunc
  • func (a *API) Walk(callback func(path string, endpoints *Endpoint))
• type Contact
• type Docs
• type Endpoint
• type Endpoints
  • func (e *Endpoints) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (e *Endpoints) Walk(fn func(endpoint *Endpoint))
• type Header
• type Info
• type Items
• type License
• type Object
• type Parameter
• type Property
• type Response
• type Schema
  • func MakeSchema(prototype interface{}) *Schema
• type SecurityRequirement
  • func (s *SecurityRequirement) MarshalJSON() ([]byte, error)
• type SecurityScheme
• type SecuritySchemeOption
  • func APIKeySecurity(name, in string) SecuritySchemeOption
  • func BasicSecurity() SecuritySchemeOption
  • func OAuth2Scope(scope, description string) SecuritySchemeOption
  • func OAuth2Security(flow, authorizationURL, tokenURL string) SecuritySchemeOption
  • func SecuritySchemeDescription(description string) SecuritySchemeOption
• type Tag

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"`
	Host                string                    `json:"host"`
	SecurityDefinitions map[string]SecurityScheme `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) 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 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"`

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

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

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"`
	License        License `json:"license"`
}

Info represents the info entity from the swagger definition

type Items

type Items struct {
	Type   string `json:"type,omitempty"`
	Format string `json:"format,omitempty"`
	Ref    string `json:"$ref,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"`
	Format     string              `json:"format,omitempty"`
	Required   []string            `json:"required,omitempty"`
	Properties map[string]Property `json:"properties,omitempty"`
}

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"`
	Format      string  `json:"format,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"`
	Format      string       `json:"format,omitempty"`
	Ref         string       `json:"$ref,omitempty"`
	Example     string       `json:"example,omitempty"`
	Items       *Items       `json:"items,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
}

func (*SecurityRequirement) MarshalJSON

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

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