legacy

Documentation

Overview

Package legacy implements a router.

It differs from the gorilla/mux router: * it provides granular errors: "path not found", "method not allowed", "variable missing from path" * it does not handle matching routes with extensions (e.g. /books/{id}.json) * it handles path patterns with a different syntax (e.g. /params/{x}/{y}/{z.*})

Example

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/getkin/kin-openapi/openapi3"
	"github.com/getkin/kin-openapi/openapi3filter"
	"github.com/getkin/kin-openapi/routers/legacy"
)

const spec = `
openapi: 3.0.0
info:
  title: My API
  version: 0.0.1
paths:
  /:
    post:
      responses:
        default:
          description: ''
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Cat'
              - $ref: '#/components/schemas/Dog'
              discriminator:
                propertyName: pet_type

components:
  schemas:
    Pet:
      type: object
      required: [pet_type]
      properties:
        pet_type:
          type: string
      discriminator:
        propertyName: pet_type

    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          breed:
            type: string
            enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        properties:
          hunts:
            type: boolean
          age:
            type: integer
`

func main() {
	loader := openapi3.NewLoader()
	doc, err := loader.LoadFromData([]byte(spec))
	if err != nil {
		panic(err)
	}
	if err := doc.Validate(loader.Context); err != nil {
		panic(err)
	}

	router, err := legacy.NewRouter(doc)
	if err != nil {
		panic(err)
	}

	p, err := json.Marshal(map[string]any{
		"pet_type": "Cat",
		"breed":    "Dingo",
		"bark":     true,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest(http.MethodPost, "/", bytes.NewReader(p))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")

	route, pathParams, err := router.FindRoute(req)
	if err != nil {
		panic(err)
	}

	requestValidationInput := &openapi3filter.RequestValidationInput{
		Request:    req,
		PathParams: pathParams,
		Route:      route,
	}
	if err := openapi3filter.ValidateRequest(loader.Context, requestValidationInput); err != nil {
		fmt.Println(err)
	}
}

Output:

request body has an error: doesn't match schema: input matches more than one oneOf schemas

Index

• func NewRouter(doc *openapi3.T, opts ...openapi3.ValidationOption) (routers.Router, error)
• type Router
  • func (router *Router) AddRoute(route *routers.Route) error
  • func (router *Router) FindRoute(req *http.Request) (*routers.Route, map[string]string, error)
• type Routers
  • func (rs Routers) FindRoute(req *http.Request) (routers.Router, *routers.Route, map[string]string, error)

Examples

• Package

Functions

func NewRouter

func NewRouter(doc *openapi3.T, opts ...openapi3.ValidationOption) (routers.Router, error)

NewRouter creates a new router.

If the given OpenAPIv3 document has servers, router will use them. All operations of the document will be added to the router.

Types

type Router

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

Router maps a HTTP request to an OpenAPI operation.

func (*Router) AddRoute

func (router *Router) AddRoute(route *routers.Route) error

AddRoute adds a route in the router.

func (*Router) FindRoute

func (router *Router) FindRoute(req *http.Request) (*routers.Route, map[string]string, error)

FindRoute extracts the route and parameters of an http.Request

type Routers

type Routers []*Router

Routers maps a HTTP request to a Router.

func (Routers) FindRoute

func (rs Routers) FindRoute(req *http.Request) (routers.Router, *routers.Route, map[string]string, error)

FindRoute extracts the route and parameters of an http.Request