swagger

README

How to use Swagger UI with go-restful

Get the Swagger UI sources

git clone https://github.com/wordnik/swagger-ui.git

The project contains a "dist" folder. Its contents has all the Swagger UI files you need.

The index.html has an url set to http://petstore.swagger.wordnik.com/api/api-docs. You need to change that to match your WebService JSON endpoint e.g. http://localhost:8080/apidocs.json

Now, you can install the Swagger WebService for serving the Swagger specification in JSON.

config := swagger.Config{
	WebServices:    restful.RegisteredWebServices(),
	WebServicesUrl: "http://localhost:8080",
	ApiPath:        "/apidocs.json",
	SwaggerPath:     "/apidocs/",
	SwaggerFilePath: "/Users/emicklei/Projects/swagger-ui/dist"}
swagger.InstallSwaggerService(config)		

Notes

• Use RouteBuilder.Operation(..) to set the Nickname field of the API spec
• The WebServices field of swagger.Config can be used to control which service you want to expose and document ; you can have multiple configs and therefore multiple endpoints.

Documentation

Overview

Package swagger implements the structures of the Swagger (https://github.com/wordnik/swagger-core/wiki) specification

Index

• Variables
• func InstallSwaggerService(aSwaggerConfig Config)
• func RegisterSwaggerService(config Config, wsContainer *restful.Container)
• type Api
• type ApiDeclaration
• type ApiKey
• type ApiRef
• type Authorization
• type Config
• type Endpoint
• type ErrorResponse
• type GrantType
• type Model
• type ModelProperty
• type OAuth
• type Operation
• type Parameter
• type Protocol
• type ResourceListing
• type ResponseMessage
• type SwaggerService

Variables

var LogInfo = log.Printf

LogInfo is the function that is called when this package needs to log. It defaults to log.Printf

Functions

func InstallSwaggerService

func InstallSwaggerService(aSwaggerConfig Config)

InstallSwaggerService add the WebService that provides the API documentation of all services conform the Swagger documentation specifcation. (https://github.com/wordnik/swagger-core/wiki).

func RegisterSwaggerService

func RegisterSwaggerService(config Config, wsContainer *restful.Container)

RegisterSwaggerService add the WebService that provides the API documentation of all services conform the Swagger documentation specifcation. (https://github.com/wordnik/swagger-core/wiki).

Types

type Api

type Api struct {
	Path        string      `json:"path"` // relative or absolute, must start with /
	Description string      `json:"description"`
	Operations  []Operation `json:"operations,omitempty"`
}

type ApiDeclaration

type ApiDeclaration struct {
	ApiVersion     string           `json:"apiVersion"`
	SwaggerVersion string           `json:"swaggerVersion"`
	BasePath       string           `json:"basePath"`
	ResourcePath   string           `json:"resourcePath"` // must start with /
	Consumes       []string         `json:"consumes,omitempty"`
	Produces       []string         `json:"produces,omitempty"`
	Apis           []Api            `json:"apis,omitempty"`
	Models         map[string]Model `json:"models,omitempty"`
}

https://github.com/wordnik/swagger-core/blob/scala_2.10-1.3-RC3/schemas/api-declaration-schema.json

type ApiKey

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

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

type ApiRef

type ApiRef struct {
	Path        string `json:"path"` // relative or absolute, must start with /
	Description string `json:"description"`
}

type Authorization

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

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

type Config

type Config struct {
	WebServicesUrl  string // url where the services are available, e.g. http://localhost:8080
	ApiPath         string // path where the JSON api is avaiable , e.g. /apidocs
	SwaggerPath     string // [optional] path where the swagger UI will be served, e.g. /swagger
	SwaggerFilePath string // [optional] location of folder containing Swagger HTML5 application index.html
	WebServices     []*restful.WebService
	StaticHandler   http.Handler
}

type Endpoint

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

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

type ErrorResponse

type ErrorResponse struct {
	Code   int    `json:"code"`
	Reason string `json:"reason"`
}

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"`
}

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

type Model

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

type ModelProperty

type ModelProperty struct {
	Type        string            `json:"type"`
	Description string            `json:"description"`
	Items       map[string]string `json:"items,omitempty"`
	Format      string            `json:"format"`
}

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"`
}

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

type Operation

type Operation struct {
	HttpMethod string `json:"httpMethod"`
	Nickname   string `json:"nickname"`
	Type       string `json:"type"` // in 1.1 = DataType
	// ResponseClass    string            `json:"responseClass"` obsolete in 1.2
	Summary          string            `json:"summary,omitempty"`
	Notes            string            `json:"notes,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"`
	Protocols        []Protocol        `json:"protocols,omitempty"`
}

type Parameter

type Parameter struct {
	ParamType   string `json:"paramType"` // path,query,body,header,form
	Name        string `json:"name"`
	Description string `json:"description"`
	DataType    string `json:"dataType"` // 1.2 needed?
	Type        string `json:"type"`     // integer
	Format      string `json:"format"`   // int64
	Required    bool   `json:"required"`
	Minimum     int    `json:"minimum"`
	Maximum     int    `json:"maximum"`
}

type Protocol

type Protocol struct {
}

type ResourceListing

type ResourceListing struct {
	ApiVersion     string `json:"apiVersion"`
	SwaggerVersion string `json:"swaggerVersion"` // e.g 1.2
	// BasePath       string `json:"basePath"`  obsolete in 1.1
	Apis []ApiRef `json:"apis"`
}

type ResponseMessage

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

type SwaggerService

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