swagger

README

gorilla swagger

Initial test&try to generate a swagger dynamically.

It uses gorilla-mux and kin-openapi to automatically generate and serve a swagger file.

To convert struct to schemas, we use this library. The struct should contains the appropriate struct tags to be inserted in json schema.

FAQ

1. How to add format binary? Formats date-time, email, hostname, ipv4, ipv6, uri could be added with tag jsonschema. Others format could be added with tag jsonschema_extra. Not all the formats are supported (see discovered unsupported formats here).

Discovered unsupported schema features

Formats:

• uuid is unsupported by kin-openapi

Documentation

Index

• Constants
• Variables
• type Content
• type ContentValue
• type Definitions
• type Handler
• type Operation
• type Options
• type ParameterValue
• type Router
  • func New(router *mux.Router, options Options) (*Router, error)
  • func (r Router) AddRawRoute(method string, path string, handler Handler, operation Operation) (*mux.Route, error)
  • func (r Router) AddRoute(method string, path string, handler Handler, schema Definitions) (*mux.Route, error)
  • func (r Router) GenerateAndExposeSwagger() error
• type Schema

Constants

const (
	// JSONDocumentationPath is the path of the swagger documentation in json format.
	JSONDocumentationPath = "/documentation/json"
)

Variables

var (
	// ErrGenerateSwagger throws when fails the marshalling of the swagger struct.
	ErrGenerateSwagger = errors.New("fail to generate swagger")
	// ErrValidatingSwagger throws when given swagger params are not correct.
	ErrValidatingSwagger = errors.New("fails to validate swagger")
)

var (
	// ErrResponses is thrown if error occurs generating responses schemas.
	ErrResponses = errors.New("errors generating responses schema")
	// ErrRequestBody is thrown if error occurs generating responses schemas.
	ErrRequestBody = errors.New("errors generating request body schema")
	// ErrPathParams is thrown if error occurs generating path params schemas.
	ErrPathParams = errors.New("errors generating path parameters schema")
	// ErrQuerystring is thrown if error occurs generating querystring params schemas.
	ErrQuerystring = errors.New("errors generating querystring schema")
)

Types

type Content

type Content map[string]Schema

Content is the type of a content. The key of the map define the content-type.

type ContentValue

type ContentValue struct {
	Content     Content
	Description string
}

ContentValue is the struct containing the content information.

type Definitions

type Definitions struct {
	PathParams  ParameterValue
	Querystring ParameterValue
	Headers     ParameterValue
	Cookies     ParameterValue
	RequestBody *ContentValue
	Responses   map[int]ContentValue
}

Definitions of the route.

type Handler

type Handler func(w http.ResponseWriter, req *http.Request)

Handler is the http type handler

type Operation

type Operation struct {
	*openapi3.Operation
}

Operation type

type Options

type Options struct {
	Context context.Context
	Openapi *openapi3.Swagger
}

Options to be passed to create the new router and swagger

type ParameterValue

type ParameterValue map[string]struct {
	Content     Content
	Schema      *Schema
	Description string
}

ParameterValue is the struct containing the schema or the content information. If content is specified, it takes precedence.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router handle the gorilla mux router and the swagger schema

func New

func New(router *mux.Router, options Options) (*Router, error)

New generate new router with swagger. Default to OpenAPI 3.0.0

func (Router) AddRawRoute

func (r Router) AddRawRoute(method string, path string, handler Handler, operation Operation) (*mux.Route, error)

AddRawRoute add route to router with specific method, path and handler. Add the router also to the swagger schema, after validating it

func (Router) AddRoute

func (r Router) AddRoute(method string, path string, handler Handler, schema Definitions) (*mux.Route, error)

AddRoute add a route with json schema inferted by passed schema.

func (Router) GenerateAndExposeSwagger

func (r Router) GenerateAndExposeSwagger() error

GenerateAndExposeSwagger creates a /documentation/json route on router and expose the generated swagger

type Schema

type Schema struct {
	Value                     interface{}
	AllowAdditionalProperties bool
}

Schema contains the value and if properties allow additional properties.