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 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/polarismesh/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
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-" )
Variables ¶
This section is empty.
Functions ¶
func BuildSwagger ¶
BuildSwagger returns a Swagger object for all services' API endpoints.
func DefaultNameHandler ¶
DefaultNameHandler GoRestfulDefinition -> GoRestfulDefinition (not changed)
func GoLowerCamelCasedNameHandler ¶
GoLowerCamelCasedNameHandler HTTPRestfulDefinition -> httpRestfulDefinition
func LowerCamelCasedNameHandler ¶
LowerCamelCasedNameHandler GoRestfulDefinition -> goRestfulDefinition
func LowerSnakeCasedNameHandler ¶
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 ¶
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 MapModelTypeNameFunc ¶
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 ¶
MapSchemaFormatFunc can be used to modify typeName at definition time. To use it set the SchemaFormatHandler in the config.
type PostBuildSwaggerObjectFunc ¶
PostBuildSwaggerObjectFunc can be used to change the creates Swagger Object before serving it. To use it set the PostBuildSwaggerObjectHandler in the config.
Source Files