swagger

README

swagger

Go package to export API doc for swagger-ui Copied from https://github.com/proullon/swagger, we may do a pull request later if we polish code

What is swagger ?

Check out Swagger-ui

Documentation

Index

• func GoTypeToSwagger(t reflect.Type) (string, string, string)
• func ModelName(t reflect.Type) string
• type Api
• type ApiDeclaration
  • func NewApiDeclaration(version string, basePath string) *ApiDeclaration
  • func (decl *ApiDeclaration) AddModel(m Model)
  • func (decl *ApiDeclaration) GetSDKPaths() map[string]map[string]Operation
  • func (decl *ApiDeclaration) ToJSON() string
• type ApiKey
• type Authorization
• type Endpoint
• type GrantType
• type Model
  • func NewModel(id string) Model
• type ModelProperty
• type NestedItems
• type OAuth
• type Operation
  • func NewOperation(httpMethod, nickname, summary, typ, description string, deprecated bool) (op Operation)
  • func (op *Operation) AddParameter(param Parameter)
• type Parameter
  • func NewParameter(paramType string, name string, description string, required bool, ...) (param Parameter)
• type Path
• type ResourceListing
• type Response
• type ResponseMessage
• type Schema
• type SwaggerApiInfo

Functions

func GoTypeToSwagger

func GoTypeToSwagger(t reflect.Type) (string, string, string)

Transforms a go type to swagger type/format it is incomplete for now

func ModelName

func ModelName(t reflect.Type) string

Types

type Api

type Api struct {
	Operations []Operation      `json:"operations,omitempty"`
	Models     map[string]Model `json:"models,omitempty"`
}

Api is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#522-api-object

type ApiDeclaration

type ApiDeclaration struct {
	SwaggerApiInfo SwaggerApiInfo                  `json:"info"`
	Swagger        string                          `json:"swagger"`
	BasePath       string                          `json:"basePath,omitempty"`
	Paths          map[string]map[string]Operation `json:"paths"`
	Definitions    map[string]Model                `json:"definitions"`
}

ApiDeclaration is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#52-api-declaration

func NewApiDeclaration

func NewApiDeclaration(version string, basePath string) *ApiDeclaration

NewApiDeclaration returns a bootstrapedApiDeclaration

func (*ApiDeclaration) AddModel

func (decl *ApiDeclaration) AddModel(m Model)

AddModel does just what it says

func (*ApiDeclaration) GetSDKPaths

func (decl *ApiDeclaration) GetSDKPaths() map[string]map[string]Operation

GetSDKPaths filters out non relevant paths/operations for the SDKS at the moment just skips Operation marked as IsMonitoring

func (*ApiDeclaration) ToJSON

func (decl *ApiDeclaration) ToJSON() string

ToJSON is a shortcut to json.MarshalIndent

type ApiKey

type ApiKey struct {
	Type   string `json:"type"`   // e.g. apiKey
	PassAs string `json:"passAs"` // e.g. header
}

ApiKey is https://github.com/wordnik/swagger-core/wiki/authorizations

type Authorization

type Authorization struct {
	LocalOAuth OAuth  `json:"local-oauth"`
	ApiKey     ApiKey `json:"apiKey"`
}

Authorization is https://github.com/wordnik/swagger-core/wiki/authorizations

type Endpoint

type Endpoint struct {
	Url              string `json:"url"`
	ClientIdName     string `json:"clientIdName"`
	ClientSecretName string `json:"clientSecretName"`
	TokenName        string `json:"tokenName"`
}

Endpoint is https://github.com/wordnik/swagger-core/wiki/authorizations

type GrantType

type GrantType struct {
	LoginEndpoint        Endpoint `json:"loginEndpoint"`
	TokenName            string   `json:"tokenName"` // e.g. access_code
	TokenRequestEndpoint Endpoint `json:"tokenRequestEndpoint"`
	TokenEndpoint        Endpoint `json:"tokenEndpoint"`
}

GrantType is https://github.com/wordnik/swagger-core/wiki/authorizations

type Model

type Model struct {
	Id          string                    `json:"-"`
	Description string                    `json:"description,omitempty"`
	Required    []string                  `json:"required,omitempty"`
	Properties  map[string]*ModelProperty `json:"properties"`
}

Model is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#527-model-object

func NewModel

func NewModel(id string) Model

NewModel bootstraps a model ...

type ModelProperty

type ModelProperty struct {
	Type                 string       `json:"type,omitempty"`
	RefId                string       `json:"$ref,omitempty"`
	Format               string       `json:"format,omitempty"`
	Description          string       `json:"description,omitempty"`
	Items                *NestedItems `json:"items,omitempty"`
	AdditionalProperties *NestedItems `json:"additionalProperties,omitempty"`
	Enum                 []string     `json:"enum,omitempty"`
	Required             bool         `json:"-"`
	HideOnListing        bool         `json:"-"` //Hide this property on listing methods, activated with the swag omitinlisting
}

ModelProperty is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#528-properties-object

type NestedItems

type NestedItems struct {
	Type                 string       `json:"type,omitempty"`
	RefId                string       `json:"$ref,omitempty"`
	Items                *NestedItems `json:"items,omitempty"`
	AdditionalProperties *NestedItems `json:"additionalProperties,omitempty"`
}

TODO Unify this struct and swagger.Schema in a common struct to accomodate model, params, response types

type OAuth

type OAuth struct {
	Type       string               `json:"type"`   // e.g. oauth2
	Scopes     []string             `json:"scopes"` // e.g. PUBLIC
	GrantTypes map[string]GrantType `json:"grantTypes"`
}

OAuth is https://github.com/wordnik/swagger-core/wiki/authorizations

type Operation

type Operation struct {
	HttpMethod       string              `json:"-"`
	Nickname         string              `json:"-"`
	Items            map[string]string   `json:"items,omitempty"`
	Type             string              `json:"-"`
	Summary          string              `json:"summary,omitempty"`
	Description      string              `json:"description,omitempty"`
	Parameters       []Parameter         `json:"parameters,omitempty"`
	ResponseMessages []ResponseMessage   `json:"responseMessages,omitempty"` // optional
	Consumes         []string            `json:"consumes,omitempty"`
	Produces         []string            `json:"produces,omitempty"`
	Authorizations   []Authorization     `json:"authorizations,omitempty"`
	Responses        map[string]Response `json:"responses"`
	Tags             []string            `json:"tags,omitempty"`
	IsMonitoring     bool                `json:"-"`
	Deprecated       bool                `json:"deprecated"`
}

func NewOperation

func NewOperation(httpMethod, nickname, summary, typ, description string, deprecated bool) (op Operation)

NewOperation returns an op

func (*Operation) AddParameter

func (op *Operation) AddParameter(param Parameter)

AddParameter adds a param to operation

type Parameter

type Parameter struct {
	ParamType     string `json:"in"` // path,query,body,header,form
	Name          string `json:"name"`
	Description   string `json:"description"`
	Required      bool   `json:"required"`
	AllowMultiple bool   `json:"-"` // then it's an array

	Type             string   `json:"type,omitempty"`   // integer
	Format           string   `json:"format,omitempty"` // int64
	Enum             []string `json:"enum,omitempty"`
	CollectionFormat string   `json:"collectionFormat,omitempty"` // csv/ssv/tsv/pipe/multi, defaults to csv on swagger spec
	RefId            string   `json:"$ref,omitempty"`
	Minimum          int      `json:"minimum,omitempty"`
	Maximum          int      `json:"maximum,omitempty"`
	Default          string   `json:"default,omitempty"`

	Items  map[string]string `json:"items,omitempty"`
	Schema *Schema           `json:"schema,omitempty"`
}

func NewParameter

func NewParameter(paramType string, name string, description string, required bool, allowMultiple bool, dataType, format, refId string) (param Parameter)

type Path

type Path struct {
	Path       string `json:"-"`
	Operations map[string]Operation
}

Swagger Path https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject

type ResourceListing

type ResourceListing struct {
	ApiVersion     string `json:"apiVersion"`
	SwaggerVersion string `json:"swaggerVersion"` // e.g 1.2
}

ResourceListing is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#51-resource-listing

type Response

type Response struct {
	Description string  `json:"description"`
	Schema      *Schema `json:"schema,omitempty"`
}

type ResponseMessage

type ResponseMessage struct {
	Code          int    `json:"code"`
	Message       string `json:"message"`
	ResponseModel string `json:"responseModel"`
}

ResponseMessage is https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#525-response-message-object

type Schema

type Schema struct {
	Type  string            `json:"type,omitempty"`
	Items map[string]string `json:"items,omitempty"`
	Ref   string            `json:"$ref,omitempty"`
}

type SwaggerApiInfo

type SwaggerApiInfo struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description"`
}