apidoc

Documentation

Overview

Package apidoc provides html document builder for http requests and responses.

Index

• func DefaultStyle() *Element
• func JsonResponse(resp *http.Response) *Element
• func JsonResponseFrom(h http.Handler, r *http.Request) *Element
• func RawRequest(r *http.Request) *Element
• func RawResponse(resp *http.Response) *Element
• func RawResponseFrom(h http.Handler, r *http.Request) *Element
• func WithMethod(pattern string) string
• type Doc
  • func DocumentRouter(router http.Handler) *Doc
  • func NewDoc() *Doc
  • func (d *Doc) JsonResponse() *Element
  • func (d *Doc) NewRequest(method, path string, body io.Reader) *Element
  • func (d *Doc) Response() *Element
  • func (d *Doc) SetRouter(router http.Handler)
  • func (d *Doc) Use(r *http.Request) *Element
• type ErrHandler
• type Handler
• type RouteIndex
  • func NewRouteIndex() *RouteIndex
  • func (d *RouteIndex) Defines(pattern string)
  • func (d *RouteIndex) Document(pattern string)
  • func (d *RouteIndex) Routes() []string
  • func (d *RouteIndex) Undocumented() string
• type Router

Examples

• Doc.JsonResponse
• JsonResponseFrom
• RawResponseFrom

Functions

func DefaultStyle

func DefaultStyle() *Element

func JsonResponse

func JsonResponse(resp *http.Response) *Element

JsonResponse converts the response to a <pre> element including the body.

func JsonResponseFrom

func JsonResponseFrom(h http.Handler, r *http.Request) *Element

JsonResponseFrom records the response of the request on the handler and returns same as JsonResponse.

Example

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/gregoryv/web/apidoc"
)

func main() {
	r, _ := http.NewRequest("GET", "/", nil)

	apidoc.JsonResponseFrom(
		http.HandlerFunc(someRouter),
		r,
	).WriteTo(os.Stdout)
}

func someRouter(w http.ResponseWriter, r *http.Request) {
	if r.Method == "GET" {
		w.WriteHeader(http.StatusOK)
		fmt.Fprint(w, `{"animal": "Goat","age": 10, "friendly": "hell no, not this one"}`)
	}
	if r.Method == "POST" {
		w.WriteHeader(http.StatusCreated)
		fmt.Fprint(w, `{"message": "added"}`)
	}
}

Output:

<pre class="response">HTTP/1.1 200 OK

{
    "animal": "Goat",
    "age": 10,
    "friendly": "hell no, not this one"
}</pre>

func RawRequest

func RawRequest(r *http.Request) *Element

RawRequest returns a <pre> element with the request. The request is reusable afterwards.

func RawResponse

func RawResponse(resp *http.Response) *Element

RawResponse dumps the response including body

func RawResponseFrom

func RawResponseFrom(h http.Handler, r *http.Request) *Element

RawResponseFrom returns the full response from the request to the given handler

Example

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/gregoryv/web/apidoc"
)

func main() {
	r, _ := http.NewRequest("GET", "/", nil)
	element := apidoc.RawResponseFrom(
		http.HandlerFunc(someRouter),
		r,
	)
	element.WriteTo(os.Stdout)
}

func someRouter(w http.ResponseWriter, r *http.Request) {
	if r.Method == "GET" {
		w.WriteHeader(http.StatusOK)
		fmt.Fprint(w, `{"animal": "Goat","age": 10, "friendly": "hell no, not this one"}`)
	}
	if r.Method == "POST" {
		w.WriteHeader(http.StatusCreated)
		fmt.Fprint(w, `{"message": "added"}`)
	}
}

Output:

<pre class="response">HTTP/1.1 200 OK

{"animal": "Goat","age": 10, "friendly": "hell no, not this one"}</pre>

func WithMethod

func WithMethod(pattern string) string

WithMethod prefixes pattern with GET if it starts with /

Types

type Doc

type Doc struct {
	// Requst used when calling a response generator, eg. Response()
	// or JsonResponse()
	*http.Request

	// RouteIndex is used to index any routes you wish to document.
	*RouteIndex
	// contains filtered or unexported fields
}

func DocumentRouter

func DocumentRouter(router http.Handler) *Doc

DocumentRouter returns a Doc for the given router.

func NewDoc

func NewDoc() *Doc

NewDoc returns a documentation generator, you should set the router using SetRouter.

func (*Doc) JsonResponse

func (d *Doc) JsonResponse() *Element

JsonResponse returns a tidy json response from the last used request

Example

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/gregoryv/web/apidoc"
)

func main() {
	doc := apidoc.DocumentRouter(http.HandlerFunc(someRouter))

	doc.NewRequest("GET", "/", nil).WriteTo(os.Stdout)
	doc.JsonResponse().WriteTo(os.Stdout)
}

func someRouter(w http.ResponseWriter, r *http.Request) {
	if r.Method == "GET" {
		w.WriteHeader(http.StatusOK)
		fmt.Fprint(w, `{"animal": "Goat","age": 10, "friendly": "hell no, not this one"}`)
	}
	if r.Method == "POST" {
		w.WriteHeader(http.StatusCreated)
		fmt.Fprint(w, `{"message": "added"}`)
	}
}

Output:

<pre class="request">HTTP/1.1 GET /
</pre><pre class="response">HTTP/1.1 200 OK

{
    "animal": "Goat",
    "age": 10,
    "friendly": "hell no, not this one"
}</pre>

func (*Doc) NewRequest

func (d *Doc) NewRequest(method, path string, body io.Reader) *Element

NewRequest returns a <pre> element of a request based on the arguments. For more advanced requests use Doc.Use()

func (*Doc) Response

func (d *Doc) Response() *Element

Response returns a raw response from the last used request.

func (*Doc) SetRouter

func (d *Doc) SetRouter(router http.Handler)

func (*Doc) Use

func (d *Doc) Use(r *http.Request) *Element

Use returns a <pre> element of the given request.

type ErrHandler

type ErrHandler interface {
	Errorf(format string, args ...any)
}

type Handler

type Handler interface {
	Handle(pattern string, serve http.Handler)
}

type RouteIndex

type RouteIndex struct {

	// handles errors when calling method Defines
	ErrHandler
	// contains filtered or unexported fields
}

func NewRouteIndex

func NewRouteIndex() *RouteIndex

NewIntercepter returns a wrapper for the underlying handler registering all routes being defined. It can then be used to add more documentation to each route.

func (*RouteIndex) Defines

func (d *RouteIndex) Defines(pattern string)

Defines checks if the given pattern, [METHOD ]PATTERN, has not been defined. Use it when documenting your routes. The given error handler is used to signal error, eg. using testing.T in a test.

func (*RouteIndex) Document

func (d *RouteIndex) Document(pattern string)

func (*RouteIndex) Routes

func (d *RouteIndex) Routes() []string

Routes returns a list of defined routes as "METHOD PATTERN"

func (*RouteIndex) Undocumented

func (d *RouteIndex) Undocumented() string

Undocumented returns empty string if all routes are documented.

type Router

type Router interface {
	Handler
	http.Handler
}