README

Build Status Go Report Card GoDoc

Gorilla Swagger

Generate a swagger dynamically based on the types used to handle request and response.

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

To convert struct to schemas, we use jsonschema library.
The struct must contains the appropriate struct tags to be inserted in json schema to generate the schema dynamically.
It is always possible to add a totally custom swagger schema using kin-openapi

Usage

An example usage of this lib:

context := context.Background()
r := mux.NewRouter()
router, _ := swagger.NewRouter(r, gswagger.Options{
  Context: context,
  Openapi: &openapi3.Swagger{
    Info: &openapi3.Info{
      Title:   "my swagger title",
      Version: "1.0.0",
    },
  },
})

okHandler := func(w http.ResponseWriter, req *http.Request) {
  w.WriteHeader(http.StatusOK)
  w.Write([]byte("OK"))
}

router.AddRoute(http.MethodPost, "/users", okHandler, Definitions{
  RequestBody: &gswagger.ContentValue{
    Content: gswagger.Content{
      "application/json": {Value: User{}},
    },
  },
  Responses: map[int]gswagger.ContentValue{
    201: {
      Content: gswagger.Content{
        "text/html": {Value: ""},
      },
    },
    401: {
      Content: gswagger.Content{
        "application/json": {Value: &errorResponse{}},
      },
      Description: "invalid request",
    },
  },
})

router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{
  Responses: map[int]ContentValue{
    200: {
      Content: Content{
        "application/json": {Value: &Users{}},
      },
    },
  },
})

carSchema := openapi3.NewObjectSchema().WithProperties(map[string]*openapi3.Schema{
  "foo": openapi3.NewStringSchema(),
  "bar": openapi3.NewIntegerSchema().WithMax(15).WithMin(5),
})
requestBody := openapi3.NewRequestBody().WithJSONSchema(carSchema)
operation := swagger.NewOperation()
operation.AddRequestBody(requestBody)

router.AddRawRoute(http.MethodPost, "/cars", okHandler, operation)

This configuration will output the schema shown here

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).

  2. How to add a swagger with allOf? You can create manually a swagger with allOf using the AddRawRoute method.

  3. How to add a swagger with anyOf? You can create manually a swagger with anyOf using the AddRawRoute method.

  4. How to add a swagger with oneOf? You can create manually a swagger with oneOf using the AddRawRoute method, or use the jsonschema struct tag.

Discovered unsupported schema features

Formats:

Versioning

We use [SemVer][semver] for versioning. For the versions available, see the tags on this repository.

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const (
	// DefaultJSONDocumentationPath is the path of the swagger documentation in json format.
	DefaultJSONDocumentationPath = "/documentation/json"
	// DefaultYAMLDocumentationPath is the path of the swagger documentation in yaml format.
	DefaultYAMLDocumentationPath = "/documentation/yaml"
)

Variables

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

Functions

This section is empty.

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

            func NewOperation

            func NewOperation() Operation

              NewOperation returns an OpenApi operation.

              func (*Operation) AddRequestBody

              func (o *Operation) AddRequestBody(requestBody *openapi3.RequestBody)

                AddRequestBody set request body into operation.

                func (*Operation) AddResponse

                func (o *Operation) AddResponse(status int, response *openapi3.Response)

                  AddResponse add response to operation. It check if the description is present (otherwise default to empty string). This method does not add the default response, but it is always possible to add it manually.

                  type Options

                  type Options struct {
                  	Context context.Context
                  	Openapi *openapi3.Swagger
                  	// JSONDocumentationPath is the path exposed by json endpoint. Default to /documentation/json.
                  	JSONDocumentationPath string
                  	// YAMLDocumentationPath is the path exposed by yaml endpoint. Default to /documentation/yaml.
                  	YAMLDocumentationPath string
                  }

                    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 NewRouter

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

                          NewRouter 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.