docs package - github.com/go-oas/docs - Go Packages (original) (raw)

This section is empty.

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](/builtin#string) `yaml:"name,omitempty"`
In              [string](/builtin#string) `yaml:"in,omitempty"` 
Description     [string](/builtin#string) `yaml:"description,omitempty"`
Required        [bool](/builtin#bool)   `yaml:"required,omitempty"`
Deprecated      [bool](/builtin#bool)   `yaml:"deprecated,omitempty"`
AllowEmptyValue [bool](/builtin#bool)   `yaml:"allowEmptyValue,omitempty"`
Schema          [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.