restfulspec

package module
v2.10.2 Latest Latest
Warning

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

Go to latest
Published: Apr 1, 2024 License: MIT Imports: 8 Imported by: 305

README

go-restful-openapi

Build Status GoDoc

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/emicklei/go-restful-openapi/v2"
    restful "github.com/emicklei/go-restful/v3"
)

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

Documentation

Index

Constants

View Source
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

func BuildSwagger(config Config) *spec.Swagger

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

func DefaultNameHandler added in v2.8.0

func DefaultNameHandler(name string) string

DefaultNameHandler GoRestfulDefinition -> GoRestfulDefinition (not changed)

func GoLowerCamelCasedNameHandler added in v2.8.0

func GoLowerCamelCasedNameHandler(name string) string

GoLowerCamelCasedNameHandler HTTPRestfulDefinition -> httpRestfulDefinition

func LowerCamelCasedNameHandler added in v2.8.0

func LowerCamelCasedNameHandler(name string) string

LowerCamelCasedNameHandler GoRestfulDefinition -> goRestfulDefinition

func LowerSnakeCasedNameHandler added in v2.8.0

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 added in v2.8.0

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 added in v2.7.0

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

type SchemaType added in v2.10.1

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"})

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL