assert

package module
v0.10.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 31, 2019 License: MIT Imports: 15 Imported by: 0

README

OpenAPI - Assert

Build Status Codecov branch GoDoc Go Report Card License

Description

openapi-assert is a Go package that provides a affordable way to validate http requests and responses data throught OpenAPI Schema Specification (Swagger) and the project was inspired by PHP Swagger Assertions. It has the following features:

  • Assert request and response media types
  • Assert request and response headers
  • Assert request query strings
  • Assert request and response body.
  • Assert the entire http request and response object.

Requirements

OpenAPI Assert requires Go 1.11 or later.

Instalation

Use go get.

$ go get github.com/faabiosr/openapi-assert

Then import the package into your own code:

import "github.com/faabiosr/openapi-assert"

Usage

The package provides methods that allow you to assert raw data using swagger files.

See it in action:

package main

import (
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    log.Println(
        assert.RequestMediaType("text/html", doc, "/pet", http.MethodPost),
    )
}

If you want to assert data many times, it is recommended to create instance of assert:

package main

import (
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    assert := assert.New(doc)

    log.Println(
        assert.RequestMediaType("text/html", "/pet", http.MethodPost),
    )

    log.Println(
        assert.RequestMediaType("image/gif", "/v2/pet", http.MethodPost),
    )
}

Asserting http request object using the swagger schema file:

package main

import (
	"fmt"
	assert "github.com/faabiosr/openapi-assert"
	"log"
	"net/http"
)

func main() {
	doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

	if err != nil {
		log.Fatal(err)
	}

	assert := assert.New(doc)

	http.HandleFunc("/v2/pet", func(w http.ResponseWriter, r *http.Request) {
		err := assert.Request(r)

		fmt.Fprint(w, err)
	})

	log.Fatal(
		http.ListenAndServe("127.0.0.1:9000", nil),
	)
}

Asserting http request object using the swagger schema file:

package main

import (
	assert "github.com/faabiosr/openapi-assert"
	"log"
	"net/http"
)

func main() {
	doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

	if err != nil {
		log.Fatal(err)
	}

	assert := assert.New(doc)

	res, err := http.Get("https://petstore.swagger.io/v2/pet/111111422")

	if err != nil {
		log.Fatal(err)
	}

	log.Println(assert.Response(res))
}

Examples

Development

Requirements
  • Install Go
Makefile
# Clean up
$ make clean

# Download project dependencies
$ make configure

# Run tests and generates html coverage file
$ make cover

# Format all go files
$ make fmt

# Run tests
$make test

License

This project is released under the MIT licence. See LICENSE for more details.

Documentation

Overview

Package assert provides methods that allow you to assert raw data using swagger files.

Example Usage

See it in action: 

package main

import (
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    log.Println(
        assert.RequestMediaType("text/html", doc, "/pet", http.MethodPost),
    )
}

If you want to assert data many times, it is recommended to create instance of assert: 

package main

import (
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    assert := assert.New(doc)

    log.Println(
        assert.RequestMediaType("text/html", "/pet", http.MethodPost),
    )

    log.Println(
        assert.RequestMediaType("image/gif", "/v2/pet", http.MethodPost),
    )
}

Asserting http request object using the swagger schema file: 

package main

import (
    "fmt"
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    assert := assert.New(doc)

    http.HandleFunc("/v2/pet", func(w http.ResponseWriter, r *http.Request) {
        err := assert.Request(r)

        fmt.Fprintf(w, err)
    })

    log.Fatal(
        http.ListenAndServer("127.0.0.1:9000", nil),
    )
}

Asserting http response object using the swagger schema file: 

package main

import (
    assert "github.com/faabiosr/openapi-assert"
    "log"
    "net/http"
)

func main() {
    doc, err := assert.LoadFromURI("http://petstore.swagger.io/v2/swagger.json")

    if err != nil {
        log.Fatal(err)
    }

    assert := assert.New(doc

    res, err := http.Get("https://petstore.swagger.io/v2/pet/111111422")

    if err != nil {
        log.Fatal(err)
    }

    log.Println(assert.Response(res))
}

Index

Constants

This section is empty.

Variables

View Source 
var (
	// FailMessage define the base error message.
	FailMessage = "failed asserting that %s"

	// ErrMediaType shows the media type error format.
	ErrMediaType = `'%s' is an allowed media type (%s)`

	// ErrRequestHeaders shows the request headers error format.
	ErrRequestHeaders = `'%s' is a valid request header (%s)`

	// ErrRequestQuery shows the request query error format.
	ErrRequestQuery = `'%s' is a valid request query (%s)`

	// ErrResponseHeaders shows the response headers error format.
	ErrResponseHeaders = `'%s' is a valid response header (%s)`

	// ErrValidation wrap the json schema validation errors
	ErrValidation = "unable to load the validation"

	// ErrJson wrap the json marshall errors
	ErrJson = "unable to marshal"

	// ErrRequestBody shows the request body error format.
	ErrRequestBody = `'%s' is a valid request body (%s)`

	// ErrResponseBody shows the response body error format.
	ErrResponseBody = `'%s' is a valid response body (%s)`
)
View Source 
var (
	// ErrResourceURI returns an error when uri does not match.
	ErrResourceURI = "resource uri does not match"

	// ErrSwaggerLoad returns an error when load swagger document.
	ErrSwaggerLoad = "unable to load the document by uri"

	// ErrSwaggerExpand returns an error of expanding schema.
	ErrSwaggerExpand = "unable to expand the document"

	// ErrNodeNotFound returns an error when node does not exists.
	ErrNodeNotFound = "node does not exists"

	// ErrBodyNotFound returns an error when body does not exists.
	ErrBodyNotFound = "body does not exists"
)

Functions

func Request added in v0.8.0 

func Request(req *http.Request, doc Document) error

Requery asserts http request against a schema.

func RequestBody added in v0.6.0 

func RequestBody(body io.Reader, doc Document, path, method string) error

RequestBody asserts request body against a schema.

func RequestHeaders 

func RequestHeaders(header http.Header, doc Document, path, method string) error

RequestHeaders asserts rquest headers againt a schema header list.

func RequestMediaType 

func RequestMediaType(mediaType string, doc Document, path, method string) error

RequestMediaType asserts request media type against a list.

func RequestQuery 

func RequestQuery(query url.Values, doc Document, path, method string) error

RequestQuery asserts request query againt a schema.

func Response added in v0.9.0 

func Response(res *http.Response, doc Document) error

Response asserts http response against a schema.

func ResponseBody added in v0.7.0 

func ResponseBody(body io.Reader, doc Document, path, method string, statusCode int) error

ResponseBody asserts response body against a schema.

func ResponseHeaders 

func ResponseHeaders(header http.Header, doc Document, path, method string, statusCode int) error

ResponseHeaders asserts response headers againt a schema header list.

func ResponseMediaType 

func ResponseMediaType(mediaType string, doc Document, path, method string) error

ResponseMediaType asserts response media type against a list.

Types

type Assertions 

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

Assertions packs all assert methods into one structure

func New 

func New(doc Document) *Assertions

New returns the Assertions instance

func (*Assertions) Request added in v0.8.0 

func (a *Assertions) Request(req *http.Request) error

Requery asserts http request against a schema.

func (*Assertions) RequestBody added in v0.6.0 

func (a *Assertions) RequestBody(body io.Reader, path, method string) error

RequestBody asserts request body against a schema.

func (*Assertions) RequestHeaders 

func (a *Assertions) RequestHeaders(header http.Header, path, method string) error

RequestHeaders asserts rquest headers againt a schema header list.

func (*Assertions) RequestMediaType 

func (a *Assertions) RequestMediaType(mediaType, path, method string) error

RequestMediaType asserts request media type against a list.

func (*Assertions) RequestQuery 

func (a *Assertions) RequestQuery(query url.Values, path, method string) error

RequestQuery asserts request query againt a schema query list.

func (*Assertions) Response added in v0.9.0 

func (a *Assertions) Response(res *http.Response) error

Response asserts http response against a schema.

func (*Assertions) ResponseBody added in v0.7.0 

func (a *Assertions) ResponseBody(body io.Reader, path, method string, statusCode int) error

ResponseBody asserts response body against a schema.

func (*Assertions) ResponseHeaders 

func (a *Assertions) ResponseHeaders(header http.Header, path, method string, statusCode int) error

ResponseHeaders asserts response headers againt a schema header list.

func (*Assertions) ResponseMediaType 

func (a *Assertions) ResponseMediaType(mediaType, path, method string) error

ResponseMediaType asserts response media type against a list.

type Body added in v0.7.0 

type Body interface{}

Body is a document schema in json format.

type Document 

type Document interface {
	// RequestMediaTypes retrives a list of request media types allowed.
	RequestMediaTypes(path, method string) ([]string, error)

	// ResponseMediaTypes retrives a list of response media types allowed.
	ResponseMediaTypes(path, method string) ([]string, error)

	// RequestHeaders retrieves a list of request headers.
	RequestHeaders(path, method string) (Headers, error)

	// ResponseHeaders retrieves a list of response headers.
	ResponseHeaders(path, method string, statusCode int) (Headers, error)

	// RequestQuery retrieves a list of request query.
	RequestQuery(path, method string) (Query, error)

	// RequestBody retrieves the request body.
	RequestBody(path, method string) (Body, error)

	// ResponseBody retrieves the response body.
	ResponseBody(path, method string, statusCode int) (Body, error)
}

Document that defines the contract for reading OpenAPI documents.

type Headers 

type Headers map[string]interface{}

Headers is a list of headers in json schema format.

type Param 

type Param struct {
	Type        string
	Description string
	In          string
}

Param is a document parameter in json schema format.

type Query 

type Query map[string]interface{}

Query is a list of query parameters in json schema format.

type Required 

type Required []string

Required is a list of required parameters.

type Swagger 

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

Swagger stores the loaded swagger spec.

func LoadFromURI 

func LoadFromURI(uri string) (*Swagger, error)

LoadFromURI loads and expands swagger document by uri.

func (*Swagger) RequestBody added in v0.6.0 

func (s *Swagger) RequestBody(path, method string) (Body, error)

RequestBody retrieves the request body.

func (*Swagger) RequestHeaders 

func (s *Swagger) RequestHeaders(path, method string) (Headers, error)

RequestHeaders retrieves a list of request headers.

func (*Swagger) RequestMediaTypes 

func (s *Swagger) RequestMediaTypes(path, method string) ([]string, error)

RequestMediaTypes retrives a list of request media types allowed.

func (*Swagger) RequestQuery 

func (s *Swagger) RequestQuery(path, method string) (Query, error)

RequestQuery retrieves a list of request query.

func (*Swagger) ResponseBody added in v0.7.0 

func (s *Swagger) ResponseBody(path, method string, statusCode int) (Body, error)

ResponseBody retrieves the response body.

func (*Swagger) ResponseHeaders 

func (s *Swagger) ResponseHeaders(path, method string, statusCode int) (Headers, error)

ResponseHeaders retrieves a list of response headers.

func (*Swagger) ResponseMediaTypes 

func (s *Swagger) ResponseMediaTypes(path, method string) ([]string, error)

ResponseMediaTypes retrives a list of response media types allowed.

Source Files

View all Source files

Directories

Path Synopsis
_examples
echo
middleware
echo

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.