swagger

package
v0.14.2 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2015 License: MIT, Apache-2.0 Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
var LogInfo = func(format string, v ...interface{}) {

	log.Printf(format, v...)
}

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
	// Top-level API version. Is reflected in the resource listing.
	ApiVersion string
	// If set then call this handler after building the complete ApiDeclaration Map
	PostBuildHandler PostBuildDeclarationMapFunc
}

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 ModelBuildable 

type ModelBuildable interface {
	PostBuildModel(m *Model) *Model
}

ModelBuildable is used for extending Structs that need more control over how the Model appears in the Swagger api declaration.

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 PostBuildDeclarationMapFunc 

type PostBuildDeclarationMapFunc func(apiDeclarationMap map[string]ApiDeclaration)

PostBuildDeclarationMapFunc can be used to modify the api declaration map.

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 ResourceSorter 

type ResourceSorter []Resource

func (ResourceSorter) Len 

func (s ResourceSorter) Len() int

func (ResourceSorter) Less 

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

func (ResourceSorter) Swap 

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

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

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.