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 NewOpenAPIService(config Config) *restful.WebService
• type Config
• type Documented
• type MapModelTypeNameFunc
• type MapSchemaFormatFunc
• type PostBuildSwaggerObjectFunc

Constants

const KeyOpenAPITags = "openapi.tags"

KeyOpenAPITags is a Metadata key for a restful Route

Functions

func BuildSwagger

func BuildSwagger(config Config) *spec.Swagger

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

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
	// WebServicesURL is a DEPRECATED field; it never had any effect in this package.
	WebServicesURL string
	// APIPath is the path where the JSON api is avaiable , 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
}

Config holds service api metadata.

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.