restfulspec

README

go-restful-openapi

openapi extension to the go-restful package, targeting version 2.0

The following Go field tags are translated to OpenAPI equivalents

• description
• minimum
• maximum
• optional ( if set to "true" then it is not listed in required)
• unique
• modelDescription
• type (overrides the Go type String())
• enum
• readOnly

See TestThatExtraTagsAreReadIntoModel for examples.

dependencies

• go-restful
• go-openapi

Go modules

Versions v1 of this package require Go module version v2 of the go-restful package. To use version v3 of the go-restful package, you need to import v2 of this package, such as:

import (
    restfulspec "github.com/emicklei/go-restful-openapi/v2"
    restful "github.com/emicklei/go-restful/v3"
)

© 2017-2020, ernestmicklei.com. MIT License. Contributions welcome.

Documentation

Index

• Constants
• func BuildSwagger(config Config) *spec.Swagger
• func DefaultNameHandler(name string) string
• func GoLowerCamelCasedNameHandler(name string) string
• func LowerCamelCasedNameHandler(name string) string
• func LowerSnakeCasedNameHandler(name string) string
• func NewOpenAPIService(config Config) *restful.WebService
• type Config
• type DefinitionNameHandlerFunc
• type Documented
• type MapModelTypeNameFunc
• type MapSchemaFormatFunc
• type PostBuildSwaggerObjectFunc
• type PostBuildSwaggerSchema
• type SchemaType

Constants

const (
	// KeyOpenAPITags is a Metadata key for a restful Route
	KeyOpenAPITags = "openapi.tags"

	// ExtensionPrefix is the only prefix accepted for VendorExtensible extension keys
	ExtensionPrefix = "x-"
)

Functions

func BuildSwagger

func BuildSwagger(config Config) *spec.Swagger

BuildSwagger returns a Swagger object for all services' API endpoints.

func DefaultNameHandler

func DefaultNameHandler(name string) string

DefaultNameHandler GoRestfulDefinition -> GoRestfulDefinition (not changed)

func GoLowerCamelCasedNameHandler

func GoLowerCamelCasedNameHandler(name string) string

GoLowerCamelCasedNameHandler HTTPRestfulDefinition -> httpRestfulDefinition

func LowerCamelCasedNameHandler

func LowerCamelCasedNameHandler(name string) string

LowerCamelCasedNameHandler GoRestfulDefinition -> goRestfulDefinition

func LowerSnakeCasedNameHandler

func LowerSnakeCasedNameHandler(name string) string

LowerSnakeCasedNameHandler GoRestfulDefinition -> go_restful_definition

func NewOpenAPIService

func NewOpenAPIService(config Config) *restful.WebService

NewOpenAPIService returns a new WebService that provides the API documentation of all services conform the OpenAPI documentation specifcation.

Types

type Config

type Config struct {
	// [optional] If set then set this field with the generated Swagger Object
	Host string
	// [optional] If set then set this field with the generated Swagger Object
	Schemes []string
	// WebServicesURL is a DEPRECATED field; it never had any effect in this package.
	WebServicesURL string
	// APIPath is the path where the JSON api is available, e.g. /apidocs.json
	APIPath string
	// api listing is constructed from this list of restful WebServices.
	WebServices []*restful.WebService
	// [optional] on default CORS (Cross-Origin-Resource-Sharing) is enabled.
	DisableCORS bool
	// Top-level API version. Is reflected in the resource listing.
	APIVersion string
	// [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
	// [optional] If set then call this function with the generated Swagger Object
	PostBuildSwaggerObjectHandler PostBuildSwaggerObjectFunc
	// [optional] If set then call handler's function for to generate name by this handler for definition without json tag,
	//   you can use you DefinitionNameHandler, also, there are four DefinitionNameHandler provided, see definition_name.go
	DefinitionNameHandler DefinitionNameHandlerFunc
}

Config holds service api metadata.

type DefinitionNameHandlerFunc

type DefinitionNameHandlerFunc func(string) string

DefinitionNameHandlerFunc generate name by this handler for definition without json tag. example: (for more, see file definition_name_test.go)

  field	      			 definition_name
  Name `json:"name"`  ->  name
	 Name                ->  Name

there are some example provided for use

DefaultNameHandler         GoRestfulDefinition -> GoRestfulDefinition (not changed)
LowerSnakeCasedNameHandler  GoRestfulDefinition -> go_restful_definition
LowerCamelCasedNameHandler  GoRestfulDefinition -> goRestfulDefinition
GoLowerCamelCasedNameHandler HTTPRestfulDefinition -> httpRestfulDefinition

type Documented

type Documented interface {
	SwaggerDoc() map[string]string
}

Documented is

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. To use it set the ModelTypeNameHandler in the config.

type MapSchemaFormatFunc

type MapSchemaFormatFunc func(typeName string) string

MapSchemaFormatFunc can be used to modify typeName at definition time. To use it set the SchemaFormatHandler in the config.

type PostBuildSwaggerObjectFunc

type PostBuildSwaggerObjectFunc func(s *spec.Swagger)

PostBuildSwaggerObjectFunc can be used to change the creates Swagger Object before serving it. To use it set the PostBuildSwaggerObjectHandler in the config.

type PostBuildSwaggerSchema

type PostBuildSwaggerSchema interface {
	PostBuildSwaggerSchemaHandler(sm *spec.Schema)
}

type SchemaType

type SchemaType struct {
	RawType string
	Format  string
}

SchemaType is used to wrap any raw types For example, to return a "schema": "file" one can use Returns(http.StatusOK, http.StatusText(http.StatusOK), SchemaType{RawType: "file"})