swagger

package
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2014 License: MIT Imports: 6 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
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
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.