docs package - github.com/go-oas/docs

docs package - github.com/go-oas/docs - Go Packages

This section is empty.

func ServeSwaggerUI(conf *ConfigSwaggerUI) error

ServeSwaggerUI does what its name implies - runs Swagger UI on mentioned set port and route.

type Component struct {
	Schemas         Schemas         `yaml:"schemas"`
	SecuritySchemes SecuritySchemes `yaml:"securitySchemes"`
}

Component represents OAS component object.

type Components []Component

Components is a slice of Component objects.

type ConfigBuilder struct {
	CustomPath string
}

ConfigBuilder represents a config structure which will be used for the YAML Builder (BuildDocs fn).

This structure was introduced to enable possible extensions to the OAS.BuildDocs() without introducing breaking API changes.

ConfigSwaggerUI represents a structure which will be used to pass required configuration params to

the ServeSwaggerUI func.

type Contact struct {
	Email string `yaml:"email"`
}

Contact represents OAS contact object, used by Info.

type ContentType ¶

type ContentType struct {
	Name   string `yaml:"ct-name"`   
	Schema string `yaml:"ct-schema"` 
}

ContentType represents OAS content type object, used by RequestBody and Response.

type ContentTypes ¶

type ContentTypes []ContentType

ContentTypes is a slice of ContentType objects.

type ExternalDocs struct {
	Description string `yaml:"description"`
	URL         URL    `yaml:"url"`
}

ExternalDocs represents OAS externalDocs object.

Aside from base OAS structure, this is also used by Tag object.

type Info struct {
	Title          string  `yaml:"title"`
	Description    string  `yaml:"description"`
	TermsOfService URL     `yaml:"termsOfService"`
	Contact        Contact `yaml:"contact"`
	License        License `yaml:"license"`
	Version        Version `yaml:"version"`
}

Info represents OAS info object.

func (i *Info) SetContact(email string)

SetContact setts the contact on the Info struct.

func (i *Info) SetLicense(licType, url string)

SetLicense sets the license on the Info struct.

type License struct {
	Name string `yaml:"name"`
	URL  URL    `yaml:"url"`
}

License represents OAS license object, used by Info.

type OAS struct {
	OASVersion       OASVersion   `yaml:"openapi"`
	Info             Info         `yaml:"info"`
	ExternalDocs     ExternalDocs `yaml:"externalDocs"`
	Servers          Servers      `yaml:"servers"`
	Tags             Tags         `yaml:"tags"`
	Paths            Paths        `yaml:"paths"`
	Components       Components   `yaml:"components"`
	RegisteredRoutes RegRoutes    `yaml:"-"`
}

OAS - represents Open API Specification structure, in its approximated Go form.

New returns a new instance of OAS structure.

func (oas *OAS) AddRoute(path *Path)

AddRoute is used for add API documentation routes.

func (oas *OAS) AttachRoutes(fns []RouteFn)

AttachRoutes if used for attaching pre-defined API documentation routes.

fns param is a slice of functions that satisfy RouteFn signature.

func (oas *OAS) BuildDocs(conf ...ConfigBuilder) error

BuildDocs marshals the OAS struct to YAML and saves it to the chosen output file.

Returns an error if there is any.

BuildStream marshals the OAS struct to YAML and writes it to a stream.

Returns an error if there is any.

Call is used init registered functions that already exist in the *OAS, and return results if there are any.

func (oas *OAS) GetInfo() *Info

GetInfo returns pointer to the Info struct.

func (oas *OAS) GetPathByIndex(index int) *Path

GetPathByIndex returns ptr to Path structure, by its index in the parent struct of OAS.

func (oas *OAS) GetRegisteredRoutes() RegRoutes

GetRegisteredRoutes returns a map of registered RouteFn functions - in layman terms "routes".

func (oas *OAS) MapAnnotationsInPath(scanIn string, conf ...configAnnotation) error

MapAnnotationsInPath scanIn is relevant from initiator calling it.

It accepts the path in which to scan for annotations within Go files.

func (oas *OAS) SetOASVersion(ver string)

SetOASVersion sets the OAS version, by casting string to OASVersion type.

OASVersion represents the OpenAPISpecification version which will be used.

type Parameter struct {
	
	
	
	
	
	Name            string `yaml:"name,omitempty"`
	In              string `yaml:"in,omitempty"` 
	Description     string `yaml:"description,omitempty"`
	Required        bool   `yaml:"required,omitempty"`
	Deprecated      bool   `yaml:"deprecated,omitempty"`
	AllowEmptyValue bool   `yaml:"allowEmptyValue,omitempty"`
	Schema          Schema
}

Parameter represents OAS parameter object.

type Parameters []Parameter

Parameters is a slice of Parameter objects.

type Path struct {
	Route           string           `yaml:"route"`
	HTTPMethod      string           `yaml:"httpMethod"`
	Tags            []string         `yaml:"tags"`
	Summary         string           `yaml:"summary"`
	Description     string           `yaml:"description"`
	OperationID     string           `yaml:"operationId"`
	RequestBody     RequestBody      `yaml:"requestBody"`
	Responses       Responses        `yaml:"responses"`
	Security        SecurityEntities `yaml:"security,omitempty"`
	Parameters      Parameters       `yaml:"parameters,omitempty"`
	HandlerFuncName string           `yaml:"-"`
}

Path represents OAS path object.

Paths is a slice of Path objects.

RegRoutes represent a map of RouteFn's.

Note: Considering to un-export it.

type RequestBody ¶

type RequestBody struct {
	Description string       `yaml:"description"`
	Content     ContentTypes `yaml:"content"`
	Required    bool         `yaml:"required"`
}

RequestBody represents OAS requestBody object, used by Path.

type Response struct {
	Code        uint         `yaml:"code"`
	Description string       `yaml:"description"`
	Content     ContentTypes `yaml:"content"`
}

Response represents OAS response object, used by Path.

type Responses []Response

Responses is a slice of Response objects.

type RouteFn func(index int, oas *OAS)

RouteFn represents a typeFunc which needs to be satisfied in order to use default routes attaching method.

Schema represents OAS schema object, used by Component.

type SchemaProperties []SchemaProperty

SchemaProperties is a slice of SchemaProperty objects.

type SchemaProperty struct {
	Name        string      `yaml:"-"`
	Type        string      
	Format      string      `yaml:"format,omitempty"`
	Description string      `yaml:"description,omitempty"`
	Enum        []string    `yaml:"enum,omitempty"`
	Default     interface{} `yaml:"default,omitempty"`
}

SchemaProperty represents OAS schema object, used by Schema.

Schemas is a slice of Schema objects.

Security represents OAS security object.

type SecurityEntities []Security

SecurityEntities is a slice of Security objects.

type SecurityFlow struct {
	Type    string         `yaml:"type,omitempty"`
	AuthURL URL            `yaml:"authorizationUrl,omitempty"`
	Scopes  SecurityScopes `yaml:"scopes,omitempty"`
}

SecurityFlow represents OAS Flows object, used by SecurityScheme.

type SecurityFlows []SecurityFlow

SecurityFlows is a slice of SecurityFlow objects.

type SecurityScheme struct {
	Name  string        `yaml:"name,omitempty"`
	Type  string        `yaml:"type,omitempty"`
	In    string        `yaml:"in,omitempty"`
	Flows SecurityFlows `yaml:"flows,omitempty"`
}

SecurityScheme represents OAS security object, used by Component.

type SecuritySchemes []SecurityScheme

SecuritySchemes is a slice of SecuritySchemes objects.

type SecurityScope struct {
	Name        string `yaml:"name,omitempty"`
	Description string `yaml:"description,omitempty"`
}

SecurityScope represents OAS SecurityScope object, used by SecurityFlow.

type SecurityScopes []SecurityScope

SecurityScopes is a slice of SecurityScope objects.

type Server struct {
	URL URL `yaml:"url"`
}

Server represents OAS server object.

Servers is a slice of Server objects.

type Tag struct {
	Name         string       `yaml:"name"`
	Description  string       `yaml:"description"`
	ExternalDocs ExternalDocs `yaml:"externalDocs"`
}

Tag represents OAS tag object.

Tags is a slice of Tag objects.

func (tt *Tags) AppendTag(tag *Tag)

AppendTag is used to append an Tag to the slice of Tags its being called from.

func (tt *Tags) SetTag(name, tagDescription string, extDocs ExternalDocs)

SetTag is used to define a new tag based on input params, and append it to the slice of tags its being called from.

URL represents and URL which is casted from string.

Version represents a SemVer version.

type XMLEntry struct {
	Name string
}

XMLEntry represents name of XML entry in Schema object.