README
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
-
How to add format
binary
? Formatsdate-time
,email
,hostname
,ipv4
,ipv6
,uri
could be added with tagjsonschema
. Others format could be added with tagjsonschema_extra
. Not all the formats are supported (see discovered unsupported formats here). -
How to add a swagger with
allOf
? You can create manually a swagger withallOf
using theAddRawRoute
method. -
How to add a swagger with
anyOf
? You can create manually a swagger withanyOf
using theAddRawRoute
method. -
How to add a swagger with
oneOf
? You can create manually a swagger withoneOf
using theAddRawRoute
method, or use the jsonschema struct tag.
Discovered unsupported schema features
Formats:
uuid
is unsupported by kin-openapi
Versioning
We use [SemVer][semver] for versioning. For the versions available, see the tags on this repository.
Documentation
Index ¶
Constants ¶
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 ¶
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") )
Functions ¶
Types ¶
type ContentValue ¶
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 ¶
Operation type
func (*Operation) AddRequestBody ¶
func (o *Operation) AddRequestBody(requestBody *openapi3.RequestBody)
AddRequestBody set request body into operation.
func (*Operation) AddResponse ¶
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 ¶
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 (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 ¶
GenerateAndExposeSwagger creates a /documentation/json route on router and expose the generated swagger