restspec

package module
v0.4.5 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2024 License: MIT Imports: 9 Imported by: 2

README

go-restful-openapi

Build Status GoDoc

openapi extension to the go-restful package, targeting version 3.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

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

© 2024, MIT License. Contributions welcome.

Documentation

Index

Constants

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

	KeySecurityJWT = "security.jwt"

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

	MIME_FORMDATA = "multipart/form-data"
)
View Source
const (
	ExGoType       = "x-go-type"
	ExGoTypeImport = "x-go-type-import"
)

Extension Parameters

Variables

This section is empty.

Functions

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.

func ReadSample added in v0.4.0

func ReadSample(sample any) func(b *restful.RouteBuilder)

Types

type ComponentNameHandlerFunc

type ComponentNameHandlerFunc func(string) string

ComponentNameHandlerFunc 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         GoRestfulComponent -> GoRestfulComponent (not changed)
LowerSnakeCasedNameHandler  GoRestfulComponent -> go_restful_component
LowerCamelCasedNameHandler  GoRestfulComponent -> goRestfulComponent
GoLowerCamelCasedNameHandler HTTPRestfulComponent -> httpRestfulComponent

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 OpenAPI Object
	PostBuildOpenAPIObjectHandler PostBuildOpenAPIObjectFunc
	// [optional] If set then call handler's function for to generate name by this handler for definition without json tag,
	//   you can use you ComponentNameHandler, also, there are four ComponentNameHandler provided, see definition_name.go
	ComponentNameHandler ComponentNameHandlerFunc
}

Config holds service api metadata.

type Documented

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

Documented is

type File added in v0.4.3

type File = httpin.File

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 OpenAPI

type OpenAPI spec.T

func BuildOpenAPIV3

func BuildOpenAPIV3(config Config) *OpenAPI

BuildOpenAPIV3 returns a openapi object for all services' API endpoints.

type PostBuildOpenAPIObjectFunc

type PostBuildOpenAPIObjectFunc func(s *OpenAPI)

PostBuildOpenAPIObjectFunc can be used to change the creates OpenAPI Object before serving it. To use it set the PostBuildOpenAPIObjectHandler in the config.

type PostBuildOpenAPISchema

type PostBuildOpenAPISchema interface {
	PostBuildOpenAPISchemaHandler(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"})

Directories

Path Synopsis
example module

Jump to

Keyboard shortcuts

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