swagger

README

go-restful-swagger20

overview

openapi extension to the go-restful package, OpenAPI-Specification version 2.0

dependencies

• go-restful
• gopkg.in/yaml.v2

how to use

use it to replace go-restful-swagger12

config := swagger.Config{
		WebServices:    restful.DefaultContainer.RegisteredWebServices(), 
		FileStyle:	"json", //optional, default is yaml
		OpenService:     true,  //should show it in rest API service
		WebServicesUrl: "http://localhost:8080",
        ApiPath:        "/apidocs.json", //swagger doc api path
		OutFilePath: os.Getenv("SWAGGERFILEPATH"),
} 
swagger.RegisterSwaggerService(config, restful.DefaultContainer)

How to change or ignore the name of a field

go struct

	type X struct {
		A int
		B int `json:"C"`  //Will generate C here
		D int `json:"-"`  //Will ignore it
	}

result

	  "X": {
		"type": "object",
	   "properties": {
		"A": {
		 "type": "integer",
		 "format": "int32"
		},
		"C": {
		 "type": "integer",
		 "format": "int32"
		}
	   }
	  }

Example

Documentation

Overview

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

Index

• Constants
• Variables
• func InstallSwaggerService(aSwaggerConfig Config)
• type APIDefinition
• type ApiDeclarationList
  • func (l *ApiDeclarationList) At(path string) (a APIDefinition, ok bool)
  • func (l *ApiDeclarationList) Do(block func(path string, decl APIDefinition))
  • func (l *ApiDeclarationList) Put(path string, a APIDefinition)
• type Config
• type Endpoint
• type Info
• type Items
• type MapModelTypeNameFunc
• type MapSchemaFormatFunc
• type Parameters
• type Path
• type PostBuildDeclarationMapFunc
• type Response
• type SwaggerService
  • func RegisterSwaggerService(config Config, wsContainer *restful.Container) *SwaggerService
  • func (sws *SwaggerService) GetSchemaInfoList() ([]string, error)
  • func (sws SwaggerService) WriteToFile()

Constants

const (
	TypeString  = "string"
	TypeNumber  = "number"
	TypeInteger = "integer"
	TypeBoolean = "boolean"
	TypeArray   = "array"
)

const

Variables

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).

Types

type APIDefinition

type APIDefinition struct {
	Swagger     string            `yaml:"swagger" json:"swagger"`
	Info        Info              `yaml:"info" json:"info"`
	Host        string            `yaml:"host,omitempty" json:"host,omitempty"`
	Schemes     []string          `yaml:"schemes,omitempty" json:"schemes,omitempty"`
	BasePath    string            `yaml:"basePath" json:"basePath"`
	Produces    []string          `yaml:"produces,omitempty" json:"produces,omitempty"`
	Paths       map[string]*Path  `yaml:"paths" json:"paths"`
	Definitions map[string]*Items `yaml:"definitions,omitempty" json:"definitions,omitempty"`
	Parameters  map[string]*Items `yaml:"parameters,omitempty" json:"parameters,omitempty"`
}

Swagger Object

type ApiDeclarationList

type ApiDeclarationList struct {
	List []APIDefinition
}

ApiDeclarationList maintains an ordered list of ApiDeclaration.

func (*ApiDeclarationList) At

func (l *ApiDeclarationList) At(path string) (a APIDefinition, ok bool)

At returns the ApiDeclaration by its path unless absent, then ok is false

func (*ApiDeclarationList) Do

func (l *ApiDeclarationList) Do(block func(path string, decl APIDefinition))

Do enumerates all the properties, each with its assigned name

func (*ApiDeclarationList) Put

func (l *ApiDeclarationList) Put(path string, a APIDefinition)

Put adds or replaces a ApiDeclaration with this name

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
	// [optional] location of schema file
	OutFilePath string
	//是否开启显示契约的服务，默认不开启
	OpenService bool
	//写入本地磁盘的格式，json or yaml 默认yaml
	FileStyle 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
	// Swagger global info struct
	Info Info
	// [optional] If set, model builder should call this handler to get addition typename-to-swagger-format-field conversion.
	SchemaFormatHandler MapSchemaFormatFunc
	// [optional] If set, model builder should call this handler to retrieve the name for a given type.
	ModelTypeNameHandler MapModelTypeNameFunc
}

type Endpoint

type Endpoint struct {
	Summary     string              `yaml:"summary,omitempty" json:"summary,omitempty"`
	Description string              `yaml:"description,omitempty" json:"description,omitempty"`
	Tags        []string            `yaml:"tags,omitempty" json:"tags,omitempty"`
	OperationId string              `yaml:"operationId,omitempty" json:"operationId,omitempty"`
	Parameters  Parameters          `yaml:"parameters,omitempty" json:"parameters,omitempty"`
	Consumes    []string            `yaml:"consumes,omitempty" json:"consumes,omitempty"`
	Produces    []string            `yaml:"produces,omitempty" json:"produces,omitempty"`
	Responses   map[string]Response `yaml:"responses,omitempty" json:"responses,omitempty"`
}

Endpoint represents an endpoint for a path in an OpenAPI spec.

type Info

type Info struct {
	Title       string `yaml:"title" json:"title"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Version     string `yaml:"version" json:"version"`
}

type Items

type Items struct {
	Name        string      `yaml:"name,omitempty" json:"name,omitempty"`
	In          string      `yaml:"in,omitempty" json:"in,omitempty"`
	Description string      `yaml:"description,omitempty" json:"description,omitempty"`
	Required    bool        `yaml:"required,omitempty" json:"required,omitempty"`
	Type        interface{} `yaml:"type,omitempty" json:"type,omitempty"`
	Format      interface{} `yaml:"format,omitempty" json:"format,omitempty"`
	Enum        []string    `yaml:"enum,omitempty" json:"enum,omitempty"`

	ProtoTag int `yaml:"x-proto-tag,omitempty" json:"x-proto-tag,omitempty"`
	// Map type
	AdditionalProperties *Items `yaml:"additionalProperties,omitempty" json:"additionalProperties,omitempty"`
	// ref another Model
	Ref string `yaml:"$ref,omitempty" json:"$ref,omitempty"`
	// is an array
	Items      *Items            `yaml:"items,omitempty" json:"items,omitempty"`
	Schema     *Items            `yaml:"schema,omitempty" json:"schema,omitempty"`
	Properties map[string]*Items `yaml:"properties,omitempty" json:"properties,omitempty"`
}

Items represent Model properties in an OpenAPI spec.

type MapModelTypeNameFunc

type MapModelTypeNameFunc func(t reflect.Type) (string, bool)

MapModelTypeNameFunc can be used to return the desired typeName for a given type. It will return false if the default name should be used.

type MapSchemaFormatFunc

type MapSchemaFormatFunc func(typeName string) string

MapSchemaFormatFunc can be used to modify typeName at definition time.

type Parameters

type Parameters []*Items

Parameters is a slice of request parameters for a single endpoint.

type Path

type Path struct {
	Get        *Endpoint  `yaml:"get,omitempty" json:"get,omitempty"`
	Put        *Endpoint  `yaml:"put,omitempty" json:"put,omitempty"`
	Post       *Endpoint  `yaml:"post,omitempty" json:"post,omitempty"`
	Delete     *Endpoint  `yaml:"delete,omitempty" json:"delete,omitempty"`
	Patch      *Endpoint  `yaml:"patch,omitempty" json:"patch,omitempty"`
	Options    *Endpoint  `yaml:"options,omitempty" json:"options,omitempty"`
	Head       *Endpoint  `yaml:"head,omitempty" json:"head,omitempty"`
	Parameters Parameters `yaml:"parameters,omitempty" json:"parameters,omitempty"`
}

Path represents all of the endpoints and parameters available for a single

type PostBuildDeclarationMapFunc

type PostBuildDeclarationMapFunc func(apiDeclarationMap *ApiDeclarationList)

PostBuildDeclarationMapFunc can be used to modify the api declaration map.

type Response

type Response struct {
	Description string            `yaml:"description" json:"description"`
	Schema      *Items            `yaml:"schema,omitempty" json:"schema,omitempty"`
	Headers     map[string]*Items `yaml:"headers,omitempty" json:"headers,omitempty"`
}

Response represents the response object in an OpenAPI spec.

type SwaggerService

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

func RegisterSwaggerService

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

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

func (*SwaggerService) GetSchemaInfoList

func (sws *SwaggerService) GetSchemaInfoList() ([]string, error)

Get Schema information

func (SwaggerService) WriteToFile

func (sws SwaggerService) WriteToFile()