assert

README

OpenAPI - Assert

Asserting data against OpenAPI docs. This project is inspired by PHP Swagger Assertions.

Instalation

OpenAPI Assert requires Go 1.11 or later.

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

If you want to get an specific version, please use the example below:

go get gopkg.in/faabiosr/openapi-assert.v0

Usage

The package provides methods that allow you to write simple swagger validations.

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 many times, see below:

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")
    assert := assert.New(doc)

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

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

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

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 write simple swagger validations.

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 many times, see below:

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")
    assert := assert.New(doc)

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

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

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

Index

• Variables
• func RequestHeaders(header http.Header, doc Document, path, method string) error
• func RequestMediaType(mediaType string, doc Document, path, method string) error
• func RequestQuery(query url.Values, doc Document, path, method string) error
• func ResponseHeaders(header http.Header, doc Document, path, method string, statusCode int) error
• func ResponseMediaType(mediaType string, doc Document, path, method string) error
• type Assertions
  • func New(doc Document) *Assertions
  • func (a *Assertions) RequestHeaders(header http.Header, path, method string) error
  • func (a *Assertions) RequestMediaType(mediaType, path, method string) error
  • func (a *Assertions) RequestQuery(query url.Values, path, method string) error
  • func (a *Assertions) ResponseHeaders(header http.Header, path, method string, statusCode int) error
  • func (a *Assertions) ResponseMediaType(mediaType, path, method string) error
• type Document
• type Headers
• type Param
• type Query
• type Required
• type Swagger
  • func LoadFromURI(uri string) (*Swagger, error)
  • func (s *Swagger) FindNode(segments ...string) (interface{}, error)
  • func (s *Swagger) FindPath(uri string) (string, error)
  • func (s *Swagger) RequestHeaders(path, method string) (Headers, error)
  • func (s *Swagger) RequestMediaTypes(path, method string) ([]string, error)
  • func (s *Swagger) RequestQuery(path, method string) (Query, error)
  • func (s *Swagger) ResponseHeaders(path, method string, statusCode int) (Headers, error)
  • func (s *Swagger) ResponseMediaTypes(path, method string) ([]string, error)

Variables

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

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

Functions

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

type Document interface {
	// FindPath searches for an uri in document and returns the path.
	FindPath(uri string) (string, error)

	// FindNode searches a node by using the segments in the document.
	FindNode(segments ...string) (interface{}, error)

	// 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)
}

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

func (s *Swagger) FindNode(segments ...string) (interface{}, error)

FindNode searches a node using segments in the schema.

func (*Swagger) FindPath

func (s *Swagger) FindPath(uri string) (string, error)

FindPath searches for an uri in document and returns the path.

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