echoswagger

package module
v2.1.1 Latest Latest
Warning

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

 Go to latest Published: May 20, 2020 License: MIT Imports: 14 Imported by: 0

README

English | 简体中文

Echoswagger

Swagger UI generator for Echo framework

Go Report Card Build Status codecov

Feature

  • No SwaggerUI HTML/CSS dependency
  • Highly integrated with Echo, low intrusive design
  • Take advantage of the strong typing language and chain programming to make it easy to use
  • Recycle garbage in time, low memory usage

Installation

go get github.com/pangpanglabs/echoswagger

Go modules support

If your project has migrated to Go modules, you can:

  • Choose v2 version of Echoswagger for Echo version v4.
  • Choose v1 version of Echoswagger for Echo version <= v3 .

To use v2 version, just do:

  • go get github.com/pangpanglabs/echoswagger/v2
  • import github.com/labstack/echo/v4 and github.com/pangpanglabs/echoswagger/v2 in your project

Meanwhile, v1 version will still be updated if needed. For more details of Go modules, please refer to Go Wiki.

Example

package main

import (
	"net/http"

	"github.com/labstack/echo"
	"github.com/pangpanglabs/echoswagger"
)

func main() {
	// ApiRoot with Echo instance
	r := echoswagger.New(echo.New(), "/doc", nil)

	// Routes with parameters & responses
	r.POST("/", createUser).
		AddParamBody(User{}, "body", "User input struct", true).
		AddResponse(http.StatusCreated, "successful", nil, nil)

	// Start server
	r.Echo().Logger.Fatal(r.Echo().Start(":1323"))
}

type User struct {
	Name string
}

// Handler
func createUser(c echo.Context) error {
	return c.JSON(http.StatusCreated, nil)
}

Usage

Create a ApiRoot with New(), which is a wrapper of echo.New()
r := echoswagger.New(echo.New(), "/doc", nil)

You can use the result ApiRoot instance to:

  • Setup Security definitions, request/response Content-Types, UI options, Scheme, etc.
r.AddSecurityAPIKey("JWT", "JWT Token", echoswagger.SecurityInHeader).
	SetRequestContentType("application/x-www-form-urlencoded", "multipart/form-data").
	SetUI(UISetting{HideTop: true}).
	SetScheme("https", "http")
  • Get echo.Echo instance.
r.Echo()
  • Registers a new GET, POST, PUT, DELETE, OPTIONS, HEAD or PATCH route in default group, these are wrappers of Echo's create route methods. It returns a new Api instance.
r.GET("/:id", handler)
  • And: ↓
Create a ApiGroup with Group(), which is a wrapper of echo.Group()
g := r.Group("Users", "/users")

You can use the result ApiGroup instance to:

  • Set description, etc.
g.SetDescription("The desc of group")
  • Set security for all routes in this group.
g.SetSecurity("JWT")
  • Get echo.Group instance.
g.EchoGroup()
  • And: ↓
Registers a new route in ApiGroup

GET, POST, PUT, DELETE, OPTIONS, HEAD or PATCH methods are supported by Echoswagger, these are wrappers of Echo's create route methods.

a := g.GET("/:id", handler)

You can use the result Api instance to:

  • Add parameter with these methods:
AddParamPath(p interface{}, name, desc string)

AddParamPathNested(p interface{})

AddParamQuery(p interface{}, name, desc string, required bool)

AddParamQueryNested(p interface{})

AddParamForm(p interface{}, name, desc string, required bool)

AddParamFormNested(p interface{})

AddParamHeader(p interface{}, name, desc string, required bool)

AddParamHeaderNested(p interface{})

AddParamBody(p interface{}, name, desc string, required bool)

AddParamFile(name, desc string, required bool)

The methods which name's suffix are Nested means these methods treat parameter p 's fields as paramters, so it must be a struct type.

e.g.

type SearchInput struct {
	Q         string `query:"q" swagger:"desc(Keywords),required"`
	SkipCount int    `query:"skipCount"`
}
a.AddParamQueryNested(SearchInput{})

Is equivalent to:

a.AddParamQuery("", "q", "Keywords", true).
	AddParamQuery(0, "skipCount", "", false)
  • Add responses.
a.AddResponse(http.StatusOK, "response desc", body{}, nil)
  • Set Security, request/response Content-Types, summary, description, etc.
a.SetSecurity("JWT").
	SetResponseContentType("application/xml").
	SetSummary("The summary of API").
	SetDescription("The desc of API")
  • Get echo.Route instance.
a.Route()
With swagger tag, you can set more info with AddParam... methods.

e.g.

type User struct {
	Age    int       `swagger:"min(0),max(99)"`
	Gender string    `swagger:"enum(male|female|other),required"`
	Money  []float64 `swagger:"default(0),readOnly"`
}
a.AddParamBody(&User{}, "Body", "", true)

The definition is equivalent to:

{
    "definitions": {
        "User": {
            "type": "object",
            "properties": {
                "Age": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0,
                    "maximum": 99
                },
                "Gender": {
                    "type": "string",
                    "enum": [
                        "male",
                        "female",
                        "other"
                    ],
                    "format": "string"
                },
                "Money": {
                    "type": "array",
                    "items": {
                        "type": "number",
                        "default": 0,
                        "format": "double"
                    },
                    "readOnly": true
                }
            },
            "required": [
                "Gender"
            ]
        }
    }
}

Supported swagger tags:

Tag Type Description
desc string Description.
min number -
max number -
minLen integer -
maxLen integer -
allowEmpty boolean Sets the ability to pass empty-valued parameters. This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value. Default value is false.
required boolean Determines whether this parameter is mandatory. If the parameter is in "path", this property is true without setting. Otherwise, the property MAY be included and its default value is false.
readOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.
enum [*] Enumerate value, multiple values should be separated by "|"
default * Default value, which type is same as the field's type.

Reference

OpenAPI Specification 2.0

License

MIT

Documentation

Index

Constants

View Source 
const (
	DefPrefix      = "#/definitions/"
	SwaggerVersion = "2.0"
	SpecName       = "swagger.json"
)
View Source 
const DefaultCDN = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.24.3"

CDN refer to https://www.jsdelivr.com/package/npm/swagger-ui-dist

View Source 
const SwaggerUIContent = `` /* 2249-byte string literal not displayed */

Variables

This section is empty.

Functions

This section is empty.

Types

type Api 

type Api interface {
	// AddParamPath adds path parameter.
	AddParamPath(p interface{}, name, desc string) Api

	// AddParamPathNested adds path parameters nested in p.
	// P must be struct type.
	AddParamPathNested(p interface{}) Api

	// AddParamQuery adds query parameter.
	AddParamQuery(p interface{}, name, desc string, required bool) Api

	// AddParamQueryNested adds query parameters nested in p.
	// P must be struct type.
	AddParamQueryNested(p interface{}) Api

	// AddParamForm adds formData parameter.
	AddParamForm(p interface{}, name, desc string, required bool) Api

	// AddParamFormNested adds formData parameters nested in p.
	// P must be struct type.
	AddParamFormNested(p interface{}) Api

	// AddParamHeader adds header parameter.
	AddParamHeader(p interface{}, name, desc string, required bool) Api

	// AddParamHeaderNested adds header parameters nested in p.
	// P must be struct type.
	AddParamHeaderNested(p interface{}) Api

	// AddParamBody adds body parameter.
	AddParamBody(p interface{}, name, desc string, required bool) Api

	// AddParamFile adds file parameter.
	AddParamFile(name, desc string, required bool) Api

	// AddResponse adds response for Api.
	// Header must be struct type.
	AddResponse(code int, desc string, schema interface{}, header interface{}) Api

	// SetRequestContentType sets request content types.
	SetRequestContentType(types ...string) Api

	// SetResponseContentType sets response content types.
	SetResponseContentType(types ...string) Api

	// SetOperationId sets operationId
	SetOperationId(id string) Api

	// SetDeprecated marks Api as deprecated.
	SetDeprecated() Api

	// SetDescription sets description.
	SetDescription(desc string) Api

	// SetExternalDocs sets external docs.
	SetExternalDocs(desc, url string) Api

	// SetSummary sets summary.
	SetSummary(summary string) Api

	// SetSecurity sets Security which names are reigistered
	// by AddSecurity... functions.
	SetSecurity(names ...string) Api

	// SetSecurityWithScope sets Security for Api which names are
	// reigistered by AddSecurity... functions.
	// Should only use when Security type is oauth2.
	SetSecurityWithScope(s map[string][]string) Api

	// Route returns the embedded `echo.Route` instance.
	Route() *echo.Route
}

type ApiGroup 

type ApiGroup interface {
	ApiRouter

	// SetDescription sets description for ApiGroup.
	SetDescription(desc string) ApiGroup

	// SetExternalDocs sets external docs for ApiGroup.
	SetExternalDocs(desc, url string) ApiGroup

	// SetSecurity sets Security for all operations within the ApiGroup
	// which names are reigistered by AddSecurity... functions.
	SetSecurity(names ...string) ApiGroup

	// SetSecurityWithScope sets Security with scopes for all operations
	// within the ApiGroup which names are reigistered
	// by AddSecurity... functions.
	// Should only use when Security type is oauth2.
	SetSecurityWithScope(s map[string][]string) ApiGroup

	// EchoGroup returns the embedded `echo.Group` instance.
	EchoGroup() *echo.Group
}

type ApiRoot 

type ApiRoot interface {
	ApiRouter

	// Group overrides `Echo#Group()` and creates ApiGroup.
	Group(name, prefix string, m ...echo.MiddlewareFunc) ApiGroup

	// SetRequestContentType sets request content types.
	SetRequestContentType(types ...string) ApiRoot

	// SetResponseContentType sets response content types.
	SetResponseContentType(types ...string) ApiRoot

	// SetExternalDocs sets external docs.
	SetExternalDocs(desc, url string) ApiRoot

	// AddSecurityBasic adds `SecurityDefinition` with type basic.
	AddSecurityBasic(name, desc string) ApiRoot

	// AddSecurityAPIKey adds `SecurityDefinition` with type apikey.
	AddSecurityAPIKey(name, desc string, in SecurityInType) ApiRoot

	// AddSecurityOAuth2 adds `SecurityDefinition` with type oauth2.
	AddSecurityOAuth2(name, desc string, flow OAuth2FlowType, authorizationUrl, tokenUrl string, scopes map[string]string) ApiRoot

	// SetUI sets UI setting.
	// If DetachSpec is false, HideTop will not take effect
	SetUI(ui UISetting) ApiRoot

	// SetScheme sets available protocol schemes.
	SetScheme(schemes ...string) ApiRoot

	// GetRaw returns raw `Swagger`. Only special case should use.
	GetRaw() *Swagger

	// SetRaw sets raw `Swagger` to ApiRoot. Only special case should use.
	SetRaw(s *Swagger) ApiRoot

	// Echo returns the embedded Echo instance
	Echo() *echo.Echo
}

func New 

func New(e *echo.Echo, docPath string, i *Info) ApiRoot

New creates ApiRoot instance. Multiple ApiRoot are allowed in one project.

type ApiRouter 

type ApiRouter interface {

	// Add overrides `Echo#Add()` and creates Api.
	Add(method, path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// GET overrides `Echo#GET()` and creates Api.
	GET(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// POST overrides `Echo#POST()` and creates Api.
	POST(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// PUT overrides `Echo#PUT()` and creates Api.
	PUT(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// DELETE overrides `Echo#DELETE()` and creates Api.
	DELETE(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// OPTIONS overrides `Echo#OPTIONS()` and creates Api.
	OPTIONS(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// HEAD overrides `Echo#HEAD()` and creates Api.
	HEAD(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

	// PATCH overrides `Echo#PATCH()` and creates Api.
	PATCH(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api
}

type Contact 

type Contact struct {
	// Name of the contact person/organization
	Name string `json:"name,omitempty"`
	// Email address of the contact person/organization
	Email string `json:"email,omitempty"`
	// URL pointing to the contact information
	URL string `json:"url,omitempty"`
}

Contact contains the API contact information.

type ExternalDocs 

type ExternalDocs struct {
	// Description is a short description of the target documentation.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	// URL for the target documentation.
	URL string `json:"url"`
}

ExternalDocs allows referencing an external resource for extended documentation. 

type Header struct {
	// Description is`a brief description of the parameter.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	//  Type of the header. it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *float64      `json:"maximum,omitempty"`
	ExclusiveMaximum bool          `json:"exclusiveMaximum,omitempty"`
	Minimum          *float64      `json:"minimum,omitempty"`
	ExclusiveMinimum bool          `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      bool          `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       float64       `json:"multipleOf,omitempty"`
}

Header represents a header parameter.

type Info 

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

Info provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience.

type Items 

type Items struct {
	//  Type of the items. it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *float64      `json:"maximum,omitempty"`
	ExclusiveMaximum bool          `json:"exclusiveMaximum,omitempty"`
	Minimum          *float64      `json:"minimum,omitempty"`
	ExclusiveMinimum bool          `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      bool          `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       float64       `json:"multipleOf,omitempty"`
}

Items is a limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body". 

type JSONLink struct {
	Title        string      `json:"title,omitempty"`
	Description  string      `json:"description,omitempty"`
	Rel          string      `json:"rel,omitempty"`
	Href         string      `json:"href,omitempty"`
	Method       string      `json:"method,omitempty"`
	Schema       *JSONSchema `json:"schema,omitempty"`
	TargetSchema *JSONSchema `json:"targetSchema,omitempty"`
	MediaType    string      `json:"mediaType,omitempty"`
	EncType      string      `json:"encType,omitempty"`
}

JSONLink represents a "link" field in a JSON hyper schema.

type JSONMedia 

type JSONMedia struct {
	BinaryEncoding string `json:"binaryEncoding,omitempty"`
	Type           string `json:"type,omitempty"`
}

JSONMedia represents a "media" field in a JSON hyper schema.

type JSONSchema 

type JSONSchema struct {
	Schema string `json:"$schema,omitempty"`
	// Core schema
	ID           string                 `json:"id,omitempty"`
	Title        string                 `json:"title,omitempty"`
	Type         JSONType               `json:"type,omitempty"`
	Items        *JSONSchema            `json:"items,omitempty"`
	Properties   map[string]*JSONSchema `json:"properties,omitempty"`
	Definitions  map[string]*JSONSchema `json:"definitions,omitempty"`
	Description  string                 `json:"description,omitempty"`
	DefaultValue interface{}            `json:"default,omitempty"`
	Example      interface{}            `json:"example,omitempty"`

	// Hyper schema
	Media    *JSONMedia `json:"media,omitempty"`
	ReadOnly bool       `json:"readOnly,omitempty"`
	Ref      string     `json:"$ref,omitempty"`
	XML      *XMLSchema `json:"xml,omitempty"`

	// Validation
	Enum                 []interface{} `json:"enum,omitempty"`
	Format               string        `json:"format,omitempty"`
	Pattern              string        `json:"pattern,omitempty"`
	Minimum              *float64      `json:"minimum,omitempty"`
	Maximum              *float64      `json:"maximum,omitempty"`
	MinLength            *int          `json:"minLength,omitempty"`
	MaxLength            *int          `json:"maxLength,omitempty"`
	Required             []string      `json:"required,omitempty"`
	AdditionalProperties *JSONSchema   `json:"additionalProperties,omitempty"`

	// Union
	AnyOf []*JSONSchema `json:"anyOf,omitempty"`
}

type JSONType 

type JSONType string

JSONType is the JSON type enum.

type License 

type License struct {
	// Name of license used for the API
	Name string `json:"name,omitempty"`
	// URL to the license used for the API
	URL string `json:"url,omitempty"`
}

License contains the license information for the API.

type OAuth2FlowType 

type OAuth2FlowType string
const (
	OAuth2FlowImplicit    OAuth2FlowType = "implicit"
	OAuth2FlowPassword    OAuth2FlowType = "password"
	OAuth2FlowApplication OAuth2FlowType = "application"
	OAuth2FlowAccessCode  OAuth2FlowType = "accessCode"
)

type Operation 

type Operation struct {
	// Tags is a list of tags for API documentation control. Tags can be used for
	// logical grouping of operations by resources or any other qualifier.
	Tags []string `json:"tags,omitempty"`
	// Summary is a short summary of what the operation does. For maximum readability
	// in the swagger-ui, this field should be less than 120 characters.
	Summary string `json:"summary,omitempty"`
	// Description is a verbose explanation of the operation behavior.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	// ExternalDocs points to additional external documentation for this operation.
	ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
	// OperationID is a unique string used to identify the operation.
	OperationID string `json:"operationId,omitempty"`
	// Consumes is a list of MIME types the operation can consume.
	Consumes []string `json:"consumes,omitempty"`
	// Produces is a list of MIME types the operation can produce.
	Produces []string `json:"produces,omitempty"`
	// Parameters is a list of parameters that are applicable for this operation.
	Parameters []*Parameter `json:"parameters,omitempty"`
	// Responses is the list of possible responses as they are returned from executing
	// this operation.
	Responses map[string]*Response `json:"responses,omitempty"`
	// Schemes is the transfer protocol for the operation.
	Schemes []string `json:"schemes,omitempty"`
	// Deprecated declares this operation to be deprecated.
	Deprecated bool `json:"deprecated,omitempty"`
	// Secury is a declaration of which security schemes are applied for this operation.
	Security []map[string][]string `json:"security,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

Operation describes a single API operation on a path.

type ParamInType 

type ParamInType string
const (
	ParamInQuery    ParamInType = "query"
	ParamInHeader   ParamInType = "header"
	ParamInPath     ParamInType = "path"
	ParamInFormData ParamInType = "formData"
	ParamInBody     ParamInType = "body"
)

type Parameter 

type Parameter struct {
	// Name of the parameter. Parameter names are case sensitive.
	Name string `json:"name"`
	// In is the location of the parameter.
	// Possible values are "query", "header", "path", "formData" or "body".
	In string `json:"in"`
	// Description is`a brief description of the parameter.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	// Required determines whether this parameter is mandatory.
	Required bool `json:"required"`
	// Schema defining the type used for the body parameter, only if "in" is body
	Schema *JSONSchema `json:"schema,omitempty"`

	//  Type of the parameter. Since the parameter is not located at the request body,
	// it is limited to simple types (that is, not an object).
	Type string `json:"type,omitempty"`
	// Format is the extending format for the previously mentioned type.
	Format string `json:"format,omitempty"`
	// AllowEmptyValue sets the ability to pass empty-valued parameters.
	// This is valid only for either query or formData parameters and allows you to
	// send a parameter with a name only or an empty value. Default value is false.
	AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
	// Items describes the type of items in the array if type is "array".
	Items *Items `json:"items,omitempty"`
	// CollectionFormat determines the format of the array if type array is used.
	// Possible values are csv, ssv, tsv, pipes and multi.
	CollectionFormat string `json:"collectionFormat,omitempty"`
	// Default declares the value of the parameter that the server will use if none is
	// provided, for example a "count" to control the number of results per page might
	// default to 100 if not supplied by the client in the request.
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *float64      `json:"maximum,omitempty"`
	ExclusiveMaximum bool          `json:"exclusiveMaximum,omitempty"`
	Minimum          *float64      `json:"minimum,omitempty"`
	ExclusiveMinimum bool          `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      bool          `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       float64       `json:"multipleOf,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

Parameter describes a single operation parameter.

type Path 

type Path struct {
	// Ref allows for an external definition of this path item.
	Ref string `json:"$ref,omitempty"`
	// Get defines a GET operation on this path.
	Get *Operation `json:"get,omitempty"`
	// Put defines a PUT operation on this path.
	Put *Operation `json:"put,omitempty"`
	// Post defines a POST operation on this path.
	Post *Operation `json:"post,omitempty"`
	// Delete defines a DELETE operation on this path.
	Delete *Operation `json:"delete,omitempty"`
	// Options defines a OPTIONS operation on this path.
	Options *Operation `json:"options,omitempty"`
	// Head defines a HEAD operation on this path.
	Head *Operation `json:"head,omitempty"`
	// Patch defines a PATCH operation on this path.
	Patch *Operation `json:"patch,omitempty"`
	// Parameters is the list of parameters that are applicable for all the operations
	// described under this path.
	Parameters []*Parameter `json:"parameters,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

Path holds the relative paths to the individual endpoints.

type RawDefine 

type RawDefine struct {
	Value  reflect.Value
	Schema *JSONSchema
}

type RawDefineDic 

type RawDefineDic map[string]RawDefine

type Response 

type Response struct {
	// Description of the response. GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	// Schema is a definition of the response structure. It can be a primitive,
	// an array or an object. If this field does not exist, it means no content is
	// returned as part of the response. As an extension to the Schema Object, its root
	// type value may also be "file".
	Schema *JSONSchema `json:"schema,omitempty"`
	// Headers is a list of headers that are sent with the response.
	Headers map[string]*Header `json:"headers,omitempty"`
	// Ref references a global API response.
	// This field is exclusive with the other fields of Response.
	Ref string `json:"$ref,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

Response describes an operation response.

type Root 

type Root struct {
	// contains filtered or unexported fields
}

func (*Root) Add 

func (r *Root) Add(method, path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) AddSecurityAPIKey 

func (r *Root) AddSecurityAPIKey(name, desc string, in SecurityInType) ApiRoot

func (*Root) AddSecurityBasic 

func (r *Root) AddSecurityBasic(name, desc string) ApiRoot

func (*Root) AddSecurityOAuth2 

func (r *Root) AddSecurityOAuth2(name, desc string, flow OAuth2FlowType, authorizationUrl, tokenUrl string, scopes map[string]string) ApiRoot

func (*Root) DELETE 

func (r *Root) DELETE(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) Echo 

func (r *Root) Echo() *echo.Echo

func (*Root) GET 

func (r *Root) GET(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) GetRaw 

func (r *Root) GetRaw() *Swagger

func (*Root) GetSpec 

func (r *Root) GetSpec(c echo.Context, docPath string) (Swagger, error)

Generate swagger spec data, without host & basePath info

func (*Root) Group 

func (r *Root) Group(name, prefix string, m ...echo.MiddlewareFunc) ApiGroup

func (*Root) HEAD 

func (r *Root) HEAD(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) OPTIONS 

func (r *Root) OPTIONS(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) PATCH 

func (r *Root) PATCH(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) POST 

func (r *Root) POST(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) PUT 

func (r *Root) PUT(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) Api

func (*Root) SetExternalDocs 

func (r *Root) SetExternalDocs(desc, url string) ApiRoot

func (*Root) SetRaw 

func (r *Root) SetRaw(s *Swagger) ApiRoot

func (*Root) SetRequestContentType 

func (r *Root) SetRequestContentType(types ...string) ApiRoot

func (*Root) SetResponseContentType 

func (r *Root) SetResponseContentType(types ...string) ApiRoot

func (*Root) SetScheme 

func (r *Root) SetScheme(schemes ...string) ApiRoot

func (*Root) SetUI 

func (r *Root) SetUI(ui UISetting) ApiRoot

type Scope 

type Scope struct {
	// Description for scope
	Description string `json:"description,omitempty"`
}

Scope corresponds to an available scope for an OAuth2 security scheme.

type SecurityDefinition 

type SecurityDefinition struct {
	// Type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
	Type string `json:"type"`
	// Description for security scheme
	Description string `json:"description,omitempty"`
	// Name of the header or query parameter to be used when type is "apiKey".
	Name string `json:"name,omitempty"`
	// In is the location of the API key when type is "apiKey".
	// Valid values are "query" or "header".
	In string `json:"in,omitempty"`
	// Flow is the flow used by the OAuth2 security scheme when type is "oauth2"
	// Valid values are "implicit", "password", "application" or "accessCode".
	Flow string `json:"flow,omitempty"`
	// The oauth2 authorization URL to be used for this flow.
	AuthorizationURL string `json:"authorizationUrl,omitempty"`
	// TokenURL  is the token URL to be used for this flow.
	TokenURL string `json:"tokenUrl,omitempty"`
	// Scopes list the  available scopes for the OAuth2 security scheme.
	Scopes map[string]string `json:"scopes,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

SecurityDefinition allows the definition of a security scheme that can be used by the operations. Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code).

type SecurityInType 

type SecurityInType string
const (
	SecurityInQuery  SecurityInType = "query"
	SecurityInHeader SecurityInType = "header"
)

type SecurityType 

type SecurityType string
const (
	SecurityBasic  SecurityType = "basic"
	SecurityOAuth2 SecurityType = "oauth2"
	SecurityAPIKey SecurityType = "apiKey"
)

type Swagger 

type Swagger struct {
	Swagger             string                         `json:"swagger,omitempty"`
	Info                *Info                          `json:"info,omitempty"`
	Host                string                         `json:"host,omitempty"`
	BasePath            string                         `json:"basePath,omitempty"`
	Schemes             []string                       `json:"schemes,omitempty"`
	Consumes            []string                       `json:"consumes,omitempty"`
	Produces            []string                       `json:"produces,omitempty"`
	Paths               map[string]interface{}         `json:"paths"`
	Definitions         map[string]*JSONSchema         `json:"definitions,omitempty"`
	Parameters          map[string]*Parameter          `json:"parameters,omitempty"`
	Responses           map[string]*Response           `json:"responses,omitempty"`
	SecurityDefinitions map[string]*SecurityDefinition `json:"securityDefinitions,omitempty"`
	Tags                []*Tag                         `json:"tags,omitempty"`
	ExternalDocs        *ExternalDocs                  `json:"externalDocs,omitempty"`
}

Swagger represents an instance of a swagger object. See https://swagger.io/specification/

type Tag 

type Tag struct {
	// Name of the tag.
	Name string `json:"name,omitempty"`
	// Description is a short description of the tag.
	// GFM syntax can be used for rich text representation.
	Description string `json:"description,omitempty"`
	// ExternalDocs is additional external documentation for this tag.
	ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
	// Extensions defines the swagger extensions.
	Extensions map[string]interface{} `json:"-"`
}

Tag allows adding meta data to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag used there.

type UISetting 

type UISetting struct {
	DetachSpec bool
	HideTop    bool
	CDN        string
}

type XMLSchema 

type XMLSchema struct {
	Name      string `json:"name,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Attribute string `json:"attribute,omitempty"`
	Wrapped   bool   `json:"wrapped,omitempty"`
}

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.