contract

Documentation

Overview

Package contract turns a document into artefacts that exercise the API it describes.

A generated document is a claim, and nothing in Spector until now could check it. The console's Execute button answers one request at a time; it is not something a repository keeps, a reviewer reads, or CI fails on. So a document and the service it describes drift apart silently, which is the one failure mode that makes documentation worse than none: it is believed.

Three artefacts come out, from one plan:

• requests.http — every endpoint as a runnable request, for the editor.
• contract_test.go — the same requests as Go tests, for CI.
• smoke.sh — status codes only, for a pipeline with nothing installed.

All three are source, not a runtime: the first version is free and every version after it belongs to the project, which is where the judgement about a particular API actually lives.

Index

• Constants
• type File
  • func Generate(doc *core.Document, opts Options) ([]File, error)
• type Options

Constants

const DefaultBaseURL = "http://localhost:8080"

DefaultBaseURL is where the artefacts point when neither the caller nor the document says otherwise.

Types

type File

type File struct {
	Name string
	Data []byte
}

File is one generated file, named relative to the output directory.

func Generate

func Generate(doc *core.Document, opts Options) ([]File, error)

Generate turns a document into contract artefacts.

type Options

type Options struct {
	// BaseURL is the API the artefacts call. Empty takes the document's first
	// server, and failing that localhost — a generated artefact should run
	// somewhere rather than not compile.
	BaseURL string
	// Package is the generated Go test package name; "contract" by default.
	Package string
	// Formats selects what is written: "http", "go", "curl". Empty means all
	// three.
	Formats []string
}

Options configures generation.