doc

README

wip

TODO:

• render Header Type info
• cleanup the example code
• add a proper readme
• tests

MAYBE TODO:

• handle doc:",omitempty" tags (skip fields whose values are empty)
• anchor pointing to an element hidden by a collapsed parent, should expand that parent.
• sdk examples
• support arbitrary documentation injection

Documentation

Index

• Constants
• type Config
  • func (k Config) Build(toc TOC) error
• type ConstTable
• type TOC
• type Topic
• type TopicList

Constants

const (
	DefaultExampleHost     = "https://api.example.com"
	DefaultFieldNameTagKey = "json"
)

const (
	FlagReqQuery   = 1 << iota // document request query params
	FlagReqHeaders             // document request http headers
	FlagRespBody               // document response body
	FlagNoReqBody              // do not document the request body

	FlagAll = FlagReqQuery | FlagReqHeaders | FlagRespBody
)

Flags signal what parts of a hit.Hit should be documented. Please note that the request body, if present, is documented by default and to not document the request body one must use the FlagNoReqBody flag.

Types

type Config

type Config struct {
	// The title for the API doc; e.g. "FooBar API v3"
	Title string

	// The path to the file to which the output should be written, if the
	// file doesn't exist it will be created, if it exists it will be truncated.
	ResultDest string // required

	// AssetsPath should be set to the folder that contains the asset files.
	AssetsPath string // required

	// AssetsDest can optionally be set to the location to which the default
	// assets, the contents of this package's /assets folder, should be copied.
	// If AssetsDest is left unset the user will need to copy the assets manually.
	AssetsDest string

	// The host which will be used in example snippets. If no host
	// is provided it will default to the value of DefaultExampleHost.
	ExampleHost string

	// The tag key to be used to retrieve a field's name, defaults
	// to "json". If no name is present in the tag value associated with
	// the key, the field's name will be used as fallback.
	FieldNameTagKey string

	// CustomTypeName allows you to customise a field's type name that is
	// displayed next to that field's name. For example you could display
	// `bigint` instead of `int64`, `object` instead of `map`, etc.
	// If no func is provided or it returns false as the second return
	// value (ok) it will fall back to the default behaviour.
	CustomTypeName func(reflect.Type) (label string, ok bool)

	// HideTestStatus allows for hiding of the test status that
	// is by default displayed next to each endpoint.
	HideTestStatus bool

	// Styles is an optional list of custom CSS files. If not empty the styles
	// will be added after the default styles to effectively overwrite them.
	Styles []string
}

func (Config) Build

func (k Config) Build(toc TOC) error

type ConstTable

type ConstTable struct {
	Name string
	Type interface{}
}

type TOC

type TOC []*TopicList

TOC is a slice of topic lists.

type Topic

type Topic struct {
	Name string
	Desc string

	// Type can be used to set the topic's "main" type. If Type is set to a
	// non-nil value, that value's type information will be rendered at the
	// top of the topic. This can be useful if the topic's const tables and
	// hit endpoints all relate to one type, setting Type to a value of that
	// type will render the type's information above the tables and endpoints.
	Type interface{}

	Tables []*ConstTable
	Epts   []*hit.Test
	File   string
}

type TopicList

type TopicList struct {
	Heading string
	List    []*Topic
}

TopicList is a list of topics grouped under a heading.