betwixt

README

betwixt

Betwixt is a documentation tool to help API integration with external sources, whilst development is ongoing. By placing the betwixt middleware between serving API and clients it's possible to use integration API tests to output up to date documentation for all.

This middleware is not router aligned so it integrates best with the standard library, otherwise adapters can be created for usage with external routers.

Output

Betwixt comes with three output formats; plaintext, markdown and Apiary flavoured markdown. Alternative outputs can be easily added if required (json, xml etc).

Plaintext

To create plaintext output middleware:

handler := http.DefaultServeMux
handler.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("content-type", "application/json")
    bytes, _ := json.Marshal(map[string]string{
        "hello": "world",
    })
    w.WriteHeader(http.StatusOK)
    w.Write(bytes)
})

var buffer bytes.Buffer
outputs := []betwixt.Output{
    output.NewPlaintext(output.MakeWriter(&buffer)),
}
capture := betwixt.New(handler, outputs)
server  := httptest.NewServer(capture)

...

if err := capture.Output(); err != nil {
    log.Fatal(err)
}

fmt.Println(buffer.String())

Example output for plaintext:

 Output:
 GET 200 - /hello
 - Parameters:
  ・ possible 2 (optional)
  ・ random   2 (optional)
 - Request Headers:
  ・ Accept-Encoding gzip
  ・ User-Agent      Go-http-client/1.1
  ・ Header          Value (optional)
 - Response Headers:
  ・ Content-Type application/json
 - Response Body:

   {"hello":"world"}

Documentation

Index

• type Betwixt
  • func New(handler http.Handler, outputs []Output) *Betwixt
  • func (b *Betwixt) Output() error
  • func (b *Betwixt) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Output
  • func Parse(value string) ([]Output, error)

Types

type Betwixt

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

Betwixt is a struct that holds all the entries and outputs to be processed

func New

func New(handler http.Handler, outputs []Output) *Betwixt

New creates a Betwixt for possible outputs

func (*Betwixt) Output

func (b *Betwixt) Output() error

Output the results

func (*Betwixt) ServeHTTP

func (b *Betwixt) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles all the middleware for creating the documents

type Output

type Output interface {
	Output([]entry.Document) error
}

Output defines an interface for consuming a document.

func Parse

func Parse(value string) ([]Output, error)

Parse a string to a possible set of outputs