README

Swagger Validation Middleware

Swagger generation and validation for gin and echo server.

Build Status GoDoc

Definition

Define API Specification using code:

get := endpoint.New("get", "/pet/{petId}", "Find pet by ID",
  endpoint.Handler(GetPet),
  endpoint.Path("petId", "integer", "", "ID of pet to return", true),
  endpoint.Query("foo", "integer", "Some foo", false),
  endpoint.Response(http.StatusOK, Pet{}, "successful operation"),
)

post := endpoint.New("post", "/pet", "Add a new pet to the store",
  endpoint.Handler(PostPet),
  endpoint.Description("Additional information on adding a pet to the store"),
  endpoint.Body(Pet{}, "Pet object that needs to be added to the store", true),
  endpoint.Response(http.StatusOK, Pet{}, "Successfully added pet"),
)

Middleware

Add the middleware to your server:

r.GET("/swagger", gin.WrapH(api.Handler(enableCors)))

r.Use(swag_validator.SwaggerValidator(api))

Swagger Docs

Generates Swagger Documentation automatically:

$ curl http://localhost:8089/swagger | jq
{
  "swagger": "2.0",
  "info": {
    "title": "Petstore",
    "description": "Sample Petstore API",
  },
  "basePath": "/",
  "paths": {
    "/pet/{petId}": {
      "get": {
        "summary": "Find pet by ID",
        "parameters": [
          {
            "in": "path",
            "name": "petId",
            "description": "ID of pet to return",
            "required": true,
            "type": "integer"
          },
...

Validation

Validate your API requests automatically based on this definition.

curl http://localhost:8089/pet/123
{"id":0,"uuid":"00000000-0000-0000-0000-000000000000","category":{"category":0,"name":""},"name":"Ollie","photoUrls":null,"tags":null,"age":0,"grumpy":false,"dob":"00

curl http://localhost:8089/pet/foo
{"error":["petId: Invalid type. Expected: integer, given: string"]}

Sample

See /sample for working example and test cases.

Credits and Thanks

Thanks to savaki, xeipuuv, and of course the gin team, for their awesome libraries that make this possible!

swag: https://github.com/savaki/swag

gojsonschema: https://github.com/xeipuuv/gojsonschema

gin: https://github.com/gin-gonic/gin

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const MaxMemory = 1 * 1024 * 1024

MaxMemory ...

Variables

This section is empty.

Functions

func SwaggerValidator

func SwaggerValidator(api *swagger.API) gin.HandlerFunc

SwaggerValidator Gin middleware

func SwaggerValidatorEcho

func SwaggerValidatorEcho(api *swagger.API) echo.MiddlewareFunc

SwaggerValidatorEcho middleware

Types

type CustomLocale

type CustomLocale struct{}

CustomLocale is a locale for schema validator

func (CustomLocale) AdditionalPropertyNotAllowed

func (l CustomLocale) AdditionalPropertyNotAllowed() string

AdditionalPropertyNotAllowed ...

func (CustomLocale) ArrayContains

func (l CustomLocale) ArrayContains() string

ArrayContains ...

func (CustomLocale) ArrayMaxItems

func (l CustomLocale) ArrayMaxItems() string

ArrayMaxItems ...

func (CustomLocale) ArrayMaxProperties

func (l CustomLocale) ArrayMaxProperties() string

ArrayMaxProperties ...

func (CustomLocale) ArrayMinItems

func (l CustomLocale) ArrayMinItems() string

ArrayMinItems ...

func (CustomLocale) ArrayMinProperties

func (l CustomLocale) ArrayMinProperties() string

ArrayMinProperties ...

func (CustomLocale) ArrayNoAdditionalItems

func (l CustomLocale) ArrayNoAdditionalItems() string

ArrayNoAdditionalItems ...

func (CustomLocale) ArrayNotEnoughItems

func (l CustomLocale) ArrayNotEnoughItems() string

ArrayNotEnoughItems ...

func (CustomLocale) CannotBeGT

func (l CustomLocale) CannotBeGT() string

CannotBeGT ...

func (CustomLocale) CannotBeUsedWithout

func (l CustomLocale) CannotBeUsedWithout() string

CannotBeUsedWithout ...

func (CustomLocale) ConditionElse

func (l CustomLocale) ConditionElse() string

ConditionElse ...

func (CustomLocale) ConditionThen

func (l CustomLocale) ConditionThen() string

ConditionThen ...

func (CustomLocale) Const

func (l CustomLocale) Const() string

Const ...

func (CustomLocale) DoesNotMatchFormat

func (l CustomLocale) DoesNotMatchFormat() string

DoesNotMatchFormat ...

func (CustomLocale) DoesNotMatchPattern

func (l CustomLocale) DoesNotMatchPattern() string

DoesNotMatchPattern ...

func (CustomLocale) Duplicated

func (l CustomLocale) Duplicated() string

Duplicated ...

func (CustomLocale) Enum

func (l CustomLocale) Enum() string

Enum ...

func (CustomLocale) ErrorFormat

func (l CustomLocale) ErrorFormat() string

ErrorFormat ...

func (CustomLocale) False

func (l CustomLocale) False() string

False returns a format-string for "false" schema validation errors

func (CustomLocale) GreaterThanZero

func (l CustomLocale) GreaterThanZero() string

GreaterThanZero ...

func (CustomLocale) HttpBadStatus

func (l CustomLocale) HttpBadStatus() string

HttpBadStatus ...

func (CustomLocale) Internal

func (l CustomLocale) Internal() string

Internal ...

func (CustomLocale) InvalidPropertyName

func (l CustomLocale) InvalidPropertyName() string

InvalidPropertyName ...

func (CustomLocale) InvalidPropertyPattern

func (l CustomLocale) InvalidPropertyPattern() string

InvalidPropertyPattern ...

func (CustomLocale) InvalidType

func (l CustomLocale) InvalidType() string

InvalidType ...

func (CustomLocale) KeyCannotBeGreaterThan

func (l CustomLocale) KeyCannotBeGreaterThan() string

KeyCannotBeGreaterThan ...

func (CustomLocale) KeyItemsMustBeOfType

func (l CustomLocale) KeyItemsMustBeOfType() string

KeyItemsMustBeOfType ...

func (CustomLocale) KeyItemsMustBeUnique

func (l CustomLocale) KeyItemsMustBeUnique() string

KeyItemsMustBeUnique ...

func (CustomLocale) MissingDependency

func (l CustomLocale) MissingDependency() string

MissingDependency ...

func (CustomLocale) MultipleOf

func (l CustomLocale) MultipleOf() string

MultipleOf ...

func (CustomLocale) MustBeGTEZero

func (l CustomLocale) MustBeGTEZero() string

MustBeGTEZero ...

func (CustomLocale) MustBeOfA

func (l CustomLocale) MustBeOfA() string

MustBeOfA ...

func (CustomLocale) MustBeOfAn

func (l CustomLocale) MustBeOfAn() string

MustBeOfAn ...

func (CustomLocale) MustBeOfType

func (l CustomLocale) MustBeOfType() string

MustBeOfType ...

func (CustomLocale) MustBeValidFormat

func (l CustomLocale) MustBeValidFormat() string

MustBeValidFormat ...

func (CustomLocale) MustBeValidRegex

func (l CustomLocale) MustBeValidRegex() string

MustBeValidRegex ...

func (CustomLocale) NotAValidType

func (l CustomLocale) NotAValidType() string

NotAValidType ...

func (CustomLocale) NumberAllOf

func (l CustomLocale) NumberAllOf() string

NumberAllOf ...

func (CustomLocale) NumberAnyOf

func (l CustomLocale) NumberAnyOf() string

NumberAnyOf ...

func (CustomLocale) NumberGT

func (l CustomLocale) NumberGT() string

NumberGT ...

func (CustomLocale) NumberGTE

func (l CustomLocale) NumberGTE() string

NumberGTE ...

func (CustomLocale) NumberLT

func (l CustomLocale) NumberLT() string

NumberLT ...

func (CustomLocale) NumberLTE

func (l CustomLocale) NumberLTE() string

NumberLTE ...

func (CustomLocale) NumberNot

func (l CustomLocale) NumberNot() string

NumberNot ...

func (CustomLocale) NumberOneOf

func (l CustomLocale) NumberOneOf() string

NumberOneOf ...

func (CustomLocale) ParseError

func (l CustomLocale) ParseError() string

ParseError ...

func (CustomLocale) ReferenceMustBeCanonical

func (l CustomLocale) ReferenceMustBeCanonical() string

ReferenceMustBeCanonical ...

func (CustomLocale) RegexPattern

func (l CustomLocale) RegexPattern() string

RegexPattern ...

func (CustomLocale) Required

func (l CustomLocale) Required() string

Required returns a format-string for "required" schema validation errors

func (CustomLocale) StringGTE

func (l CustomLocale) StringGTE() string

StringGTE ...

func (CustomLocale) StringLTE

func (l CustomLocale) StringLTE() string

StringLTE ...

func (CustomLocale) Unique

func (l CustomLocale) Unique() string

Unique ...

type RequestParameter

type RequestParameter struct {
	Name                 string         `json:"name,omitempty"`
	Type                 string         `json:"type,omitempty"`
	Format               string         `json:"format,omitempty"`
	Items                *swagger.Items `json:"items,omitempty"`
	Nullable             bool           `json:"nullable,omitempty"`
	Enum                 []string       `json:"enum,omitempty"`
	Pattern              string         `json:"pattern,omitempty"`
	MinItems             int            `json:"minItems,omitempty"`
	MaxItems             int            `json:"maxItems,omitempty"`
	UniqueItems          bool           `json:"uniqueItems,omitempty"`
	MaxLength            int            `json:"maxLength,omitempty"`
	MinLength            int            `json:"minLength,omitempty"`
	Minimum              *int64         `json:"minimum,omitempty"`
	Maximum              *int64         `json:"maximum,omitempty"`
	ExclusiveMinimum     bool           `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool           `json:"exclusiveMaximum,omitempty"`
	AdditionalProperties interface{}    `json:"additionalProperties,omitempty"`
}

RequestParameter ...

type RequestSchema

type RequestSchema struct {
	Title                string                      `json:"title"`
	Type                 string                      `json:"type"`
	Summary              string                      `json:"summary"`
	Properties           map[string]interface{}      `json:"properties"`
	Required             []string                    `json:"required"`
	Definitions          map[string]SchemaDefinition `json:"definitions"`
	AdditionalProperties bool                        `json:"additionalProperties"`
}

RequestSchema ...

type SchemaDefinition

type SchemaDefinition struct {
	Name                 string                    `json:"-"`
	Type                 string                    `json:"type"`
	Format               string                    `json:"format,omitempty"`
	Required             []string                  `json:"required,omitempty"`
	Properties           map[string]SchemaProperty `json:"properties,omitempty"`
	Enum                 []string                  `json:"enum,omitempty"`
	Pattern              string                    `json:"pattern,omitempty"`
	MinItems             int                       `json:"minItems,omitempty"`
	MaxItems             int                       `json:"maxItems,omitempty"`
	UniqueItems          bool                      `json:"uniqueItems,omitempty"`
	MinLength            int                       `json:"minLength,omitempty"`
	MaxLength            int                       `json:"maxLength,omitempty"`
	Minimum              *int64                    `json:"minimum,omitempty"`
	Maximum              *int64                    `json:"maximum,omitempty"`
	ExclusiveMinimum     bool                      `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool                      `json:"exclusiveMaximum,omitempty"`
	AdditionalProperties bool                      `json:"additionalProperties"`
}

SchemaDefinition ...

type SchemaProperty

type SchemaProperty struct {
	Type                 []string       `json:"type,omitempty"`
	Description          string         `json:"description,omitempty"`
	Enum                 []string       `json:"enum,omitempty"`
	Format               string         `json:"format,omitempty"`
	Ref                  string         `json:"$ref,omitempty"`
	Example              string         `json:"example,omitempty"`
	Items                *swagger.Items `json:"items,omitempty"`
	Pattern              string         `json:"pattern,omitempty"`
	MinItems             int            `json:"minItems,omitempty"`
	MaxItems             int            `json:"maxItems,omitempty"`
	UniqueItems          bool           `json:"uniqueItems,omitempty"`
	MinLength            int            `json:"minLength,omitempty"`
	MaxLength            int            `json:"maxLength,omitempty"`
	Minimum              *int64         `json:"minimum,omitempty"`
	Maximum              *int64         `json:"maximum,omitempty"`
	ExclusiveMinimum     bool           `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool           `json:"exclusiveMaximum,omitempty"`
	AdditionalProperties interface{}    `json:"additionalProperties,omitempty"`
}

SchemaProperty ...

Directories

Path Synopsis
sample
sample/server