swagger

README

How to use Swagger UI with go-restful

Get the Swagger UI sources (version 1.2 only)

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(),
	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.
• Use tag "description" to annotate a struct field with a description to show in the UI

Documentation

Overview

Package swagger implements the structures of the Swagger https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md

Index

• Variables
• func InstallSwaggerService(aSwaggerConfig Config)
• func RegisterSwaggerService(config Config, wsContainer *restful.Container)
• type Api
• type ApiDeclaration
• type Authorization
• type AuthorizationCode
• type Authorizations
• type Config
• type DataTypeFields
• type GrantType
• type Implicit
• type Info
• type Item
• type LoginEndpoint
• type Model
• type ModelProperty
• type Operation
• type Parameter
• type ParameterSorter
  • func (s ParameterSorter) Len() int
  • func (s ParameterSorter) Less(i, j int) bool
  • func (s ParameterSorter) Swap(i, j int)
• type Resource
• type ResourceListing
• type ResponseMessage
• type Scope
• type Special
• type SwaggerService
• type TokenEndpoint
• type TokenRequestEndpoint

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

5.2.2 API Object

type ApiDeclaration

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

5.2 API Declaration

type Authorization

type Authorization struct {
	Type       string      `json:"type"`
	PassAs     string      `json:"passAs"`
	Keyname    string      `json:"keyname"`
	Scopes     []Scope     `json:"scopes"`
	GrantTypes []GrantType `json:"grandTypes"`
}

5.1.5

type AuthorizationCode

type AuthorizationCode struct {
	TokenRequestEndpoint TokenRequestEndpoint `json:"tokenRequestEndpoint"`
	TokenEndpoint        TokenEndpoint        `json:"tokenEndpoint"`
}

5.1.9 Authorization Code Object

type Authorizations

type Authorizations map[string]Authorization

5.2.10

type Config

type Config struct {
	// url where the services are available, e.g. http://localhost:8080
	// if left empty then the basePath of Swagger is taken from the actual request
	WebServicesUrl string
	// path where the JSON api is avaiable , e.g. /apidocs
	ApiPath string
	// [optional] path where the swagger UI will be served, e.g. /swagger
	SwaggerPath string
	// [optional] location of folder containing Swagger HTML5 application index.html
	SwaggerFilePath string
	// api listing is constructed from this list of restful WebServices.
	WebServices []*restful.WebService
	// will serve all static content (scripts,pages,images)
	StaticHandler http.Handler
	// [optional] on default CORS (Cross-Origin-Resource-Sharing) is enabled.
	DisableCORS bool
}

type DataTypeFields

type DataTypeFields struct {
	Type         *string  `json:"type,omitempty"` // if Ref not used
	Ref          *string  `json:"$ref,omitempty"` // if Type not used
	Format       string   `json:"format,omitempty"`
	DefaultValue Special  `json:"defaultValue,omitempty"`
	Enum         []string `json:"enum,omitempty"`
	Minimum      string   `json:"minimum,omitempty"`
	Maximum      string   `json:"maximum,omitempty"`
	Items        []Item   `json:"items,omitempty"`
	UniqueItems  *bool    `json:"uniqueItems,omitempty"`
}

4.3.3 Data Type Fields

type GrantType

type GrantType struct {
	Implicit          Implicit          `json:"implicit"`
	AuthorizationCode AuthorizationCode `json:"authorization_code"`
}

5.1.7

type Implicit

type Implicit struct {

	// An optional alternative name to standard "access_token" OAuth2 parameter.
	TokenName string `json:"tokenName"`
	// contains filtered or unexported fields
}

5.1.8 Implicit Object

type Info

type Info struct {
	Title             string `json:"title"`
	Description       string `json:"description"`
	TermsOfServiceUrl string `json:"termsOfServiceUrl,omitempty"`
	Contact           string `json:"contact,omitempty"`
	License           string `json:"license,omitempty"`
	LicensUrl         string `json:"licensUrl,omitempty"`
}

5.1.3 Info Object

type Item

type Item struct {
	Type   *string `json:"type,omitempty"`
	Ref    *string `json:"$ref,omitempty"`
	Format string  `json:"format,omitempty"`
}

4.3.4 Items Object

type LoginEndpoint

type LoginEndpoint struct {
	// Required. The URL of the authorization endpoint for the implicit grant flow. The value SHOULD be in a URL format.
	Url string `json:"url"`
}

5.1.10 Login Endpoint Object

type Model

type Model struct {
	Id            string                   `json:"id"`
	Description   string                   `json:"description,omitempty"`
	Required      []string                 `json:"required,omitempty"`
	Properties    map[string]ModelProperty `json:"properties"`
	SubTypes      []string                 `json:"subTypes,omitempty"`
	Discriminator string                   `json:"discriminator,omitempty"`
}

5.2.6, 5.2.7 Models Object

type ModelProperty

type ModelProperty struct {
	DataTypeFields
	Description string `json:"description,omitempty"`
}

5.2.8 Properties Object

type Operation

type Operation struct {
	Type             string            `json:"type"`
	Method           string            `json:"method"`
	Summary          string            `json:"summary,omitempty"`
	Notes            string            `json:"notes,omitempty"`
	Nickname         string            `json:"nickname"`
	Authorizations   []Authorization   `json:"authorizations,omitempty"`
	Parameters       []Parameter       `json:"parameters"`
	ResponseMessages []ResponseMessage `json:"responseMessages,omitempty"` // optional
	Produces         []string          `json:"produces,omitempty"`
	Consumes         []string          `json:"consumes,omitempty"`
	Deprecated       string            `json:"deprecated,omitempty"`
}

5.2.3 Operation Object

type Parameter

type Parameter struct {
	DataTypeFields
	ParamType     string `json:"paramType"` // path,query,body,header,form
	Name          string `json:"name"`
	Description   string `json:"description"`
	Required      bool   `json:"required"`
	AllowMultiple bool   `json:"allowMultiple"`
}

5.2.4 Parameter Object

type ParameterSorter

type ParameterSorter []Parameter

func (ParameterSorter) Len

func (s ParameterSorter) Len() int

func (ParameterSorter) Less

func (s ParameterSorter) Less(i, j int) bool

func (ParameterSorter) Swap

func (s ParameterSorter) Swap(i, j int)

type Resource

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

5.1.2 Resource Object

type ResourceListing

type ResourceListing struct {
	SwaggerVersion string          `json:"swaggerVersion"` // e.g 1.2
	Apis           []Resource      `json:"apis"`
	ApiVersion     string          `json:"apiVersion"`
	Info           Info            `json:"info"`
	Authorizations []Authorization `json:"authorizations,omitempty"`
}

5.1 Resource Listing

type ResponseMessage

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

5.2.5 Response Message Object

type Scope

type Scope struct {
	// Required. The name of the scope.
	Scope string `json:"scope"`
	// Recommended. A short description of the scope.
	Description string `json:"description"`
}

5.1.6, 5.2.11

type Special

type Special string

type SwaggerService

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

type TokenEndpoint

type TokenEndpoint struct {
	// Required. The URL of the token endpoint for the authentication code grant flow. The value SHOULD be in a URL format.
	Url string `json:"url"`
	// An optional alternative name to standard "access_token" OAuth2 parameter.
	TokenName string `json:"tokenName"`
}

5.1.12 Token Endpoint Object

type TokenRequestEndpoint

type TokenRequestEndpoint struct {
	// Required. The URL of the authorization endpoint for the authentication code grant flow. The value SHOULD be in a URL format.
	Url string `json:"url"`
	// An optional alternative name to standard "client_id" OAuth2 parameter.
	ClientIdName string `json:"clientIdName"`
	// An optional alternative name to the standard "client_secret" OAuth2 parameter.
	ClientSecretName string `json:"clientSecretName"`
}

5.1.11 Token Request Endpoint Object