httpdoc

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 15, 2024 License: MIT Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultOutputName    = "apidoc"
	DefaultPageTitle     = "Example API v1"
	DefaultRootPath      = "/api"
	DefaultTCPListenPort = 8080
	DefaultExampleHost   = "https://api.example.com"
	DefaultFieldNameTag  = "json"
)

Variables

View Source 
var (
	DefaultSnippetTypes = []SnippetType{SNIPP_HTTP}
)

Functions

func Compile 

func Compile(c Config, toc TOC) error

func DefaultFieldSetting 

func DefaultFieldSetting(s reflect.StructField, t reflect.Type) (label, text string, ok bool)

func SourceURLFunc 

func SourceURLFunc(local, remote string) (f func(filename string, line int) (url string))

SourceURLFunc returns a function that can be used in the Config's SourceURL field. The arguments local and remote will be used together with the arguments of the returned function to generate the source URLs.

The argument local should be the local (i.e. on the host machine) root directory of the project for which the documentation is being generated.

The argument remote should be the remote, web-accessible, root location of the project for which the documentation is being generated. For example: 

// for a github repo the remote should have the following format.
remote = "https://github.com/<user>/<project>/tree/<branch>/"
// for a bitbucket repo the remote should have the following format.
remote = "https://bitbucket.org/<user>/<project>/src/<branch>/"

Types

type Article 

type Article struct {
	// The title of the article.
	Title string
	// A list of test groups used to generate child <article> elements
	// that contain endpoint-specific documentation.
	TestGroups []*httptest.TestGroup
	// A list of articles used to generate child <article> elements
	// that contain further documentation.
	SubArticles []*Article
	// The Text field, if set, will be used as the source for the article's
	// primary-column content. The following types are accepted:
	//	- string
	//	- *os.File
	//	- httpdoc.HTMLer
	//	- httpdoc.Valuer
	//	- interface{} (named types only)
	// Anything else will result in an error.
	//
	// If the type is string, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is *os.File, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is httpdoc.HTMLer, then its HTML() method will be used
	// to retrieve the content and it is up to the user to ensure that that
	// content is valid and safe HTML.
	//
	// If the type is httpdoc.Valuer, then its Value() method will be used
	// to get the underlying Value, the source of that Value's dynamic type
	// is then analyzed and any relevant documentation that's found will be
	// used to generate the HTML text. If the dynamic type is unnamed an
	// error will be returned instead.
	//
	// If the type is none of the above, then the type's source is analyzed
	// and any relevant documentation that's found will be used to generate
	// the HTML text. If the type is unnamed an error will be returned.
	Text interface{}
	// The Code field, if set, will be used as the source for the article's
	// example-column content. The following types are accepted:
	//	- string
	//	- *os.File
	//	- httpdoc.HTMLer
	//	- httpdoc.Valuer
	//	- interface{} (named types only)
	// Anything else will result in an error.
	//
	// If the type is string, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is *os.File, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is httpdoc.HTMLer, then its HTML() method will be used
	// to retrieve the content and it is up to the user to ensure that that
	// content is valid and safe HTML.
	//
	// If the type is httpdoc.Valuer, then its Value() method will be used to
	// get the underlying Value, that Value will then be marshaled according to
	// its MIME type (which resolved based on the Article's Type field) and the
	// result of that will be used to generate a code snippet.
	//
	// If the type is none of the above, then the value will then be marshaled
	// according to its MIME type (which resolved based on the Article's Type field)
	// and the result of that will be used to generate a code snippet.
	//
	// Note that in the last two cases, if the value's dynamic type is a struct,
	// or its base element type is a struct, then that struct's source code will
	// be analyzed to generate the documentation of the individual fields for
	// the article's primary-column.
	Code interface{}
	// The Type field can optionally be set to the MIME type that should be used
	// to present the data in the Code field. If left unset, and the Code field's
	// dynamic type implements the httptest.Body interface then its Type() method
	// will be used to resolve the MIME type. Otherwise the MIME type will default
	// to "application/json".
	Type string
	// LoadExpanded controls how much of the article's content will be loaded
	// during the initial page load.
	//
	// If set, the entire article will be loaded.
	//
	// If unset, only the "preamble" of the article will be loaded and
	// subsequent user interaction will be required to trigger the loading
	// of the rest of the content.
	//
	// NOTE: "root" articles only, this field is ignored for SubArticles.
	LoadExpanded bool
}

Article is the primary data structure of the ArticleDirectory type. It is used by httpdoc to generate <article> elements that contain documentation extracted from the Article's data.

type ArticleGroup 

type ArticleGroup struct {
	// The name of the group, optional.
	Name string
	// The list of articles that belong to the group.
	Articles []*Article
	// LoadExpanded controls how much of the group articles' content will be
	// loaded during the initial page load.
	//
	// If set, the group's entire articles will be loaded.
	//
	// If unset, only the "preambles" of the group's articles will be loaded
	// and subsequent user interaction will be required to trigger the loading
	// of the rest of the content.
	LoadExpanded bool
}

ArticleGroup is a list of loosely related articles. It is used by httpdoc to generate a named or unnamed group of sidebar items that will point to the individual articles.

type Config 

type Config struct {

	// The name of the resulting package or executable.
	//
	// If empty, it will default to DefaultOutputName.
	OutputName string
	// The directory into which the resulting package or executable should
	// be written.
	//
	// If empty, the result will be written to the directory in which
	// the client program, the one calling httpdoc.Compile, lives.
	OutputDir string
	// If set to true, httpdoc will generate the source code of the
	// program as an importable package.
	//
	// When false, httpdoc will generate and compile the program to
	// produce an executable.
	OutputPackage bool

	// The title for the generated web page.
	//
	// If empty, it will default to DefaultPageTitle.
	PageTitle string

	// The HTML content for the page's sidebar banner. It is the user's
	// responsibility to ensure that the enclosed content is valid and
	// safe HTML as it will be included verbatim in the template output.
	//
	// If empty, the value of the PageTitle field will be used in the
	// sidebar's banner as a heading.
	SidebarBannerHTML template.HTML

	// The *absolute* path to a custom CSS file.
	CustomCSSFile string

	// The root of the path for the documentation and the links within it.
	// If left empty it will default to DefaultRootPath.
	RootPath string
	// The path to the documentation server's signin endpoint.
	// If left empty it will default to DefaultSigninPath.
	SigninPath string
	// The TCP port which the resulting program should listen on.
	// If left unset, it will default to DefaultTCPListenPort.
	TCPListenPort int

	// An optional map of users and their passwords.
	Users map[string]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
	// TODO
	StripPrefix func(pattern string) string
	// The tag to be used to resolve a field's name for the documentation,
	// defaults to DefaultFieldNameTag. If no name is present in the tag's
	// value the field's name will be used as fallback.
	FieldNameTag string
	// FieldType returns the name for a specific field's type based on
	// given reflect.StructField value.
	//
	// If FieldType is nil or it returns false as the second return
	// value (ok) it will fall back to the default behaviour.
	FieldType func(field reflect.StructField) (typeName string, ok bool)
	// FieldSetting returns values that are used to document whether the given
	// field is required, optional, or something else. The structType argument
	// represents the type of struct to which the field belongs.
	//
	// The returned label is used in the corresponding element's class.
	// The returned text is used as the corresponding element's content.
	// The returned ok value indicates whether or not the field's setting
	// documentation should not be generated.
	//
	// If FieldSetting is nil then the documentation will be generated based
	// on the field's "doc" tag and if the field doesn't have a "doc" tag then
	// the field will be documented as optional.
	FieldSetting func(field reflect.StructField, structType reflect.Type) (label, text string, ok bool)
	// FieldValidation returns the documentation on the given field's validity
	// requirements. The structType argument represents the type of struct
	// to which the field belongs. If the returned text is empty then no
	// validation-specific documentation will be rendered.
	//
	// If FieldValidation is nil then no documentation on the field validity
	// requirements will be generated.
	FieldValidation func(field reflect.StructField, structType reflect.Type) (text template.HTML)
	// SourceURL returns the URL of the source code location corresponding
	// to the given filename and line. This can be used to add source links
	// to the documentation for certain objects like handlers, structs,
	// fields, and enums.
	//
	// If SourceURL is nil then no source links will be generated.
	SourceURL func(filename string, line int) (url string)
	// A list of basic SnippetTypes for which request-specific code examples
	// should be generated. If left empty it will default to DefaultSnippetTypes.
	SnippetTypes []SnippetType

	GOOS   string
	GOARCH string
	// contains filtered or unexported fields
}

type HTML 

type HTML string

HTML represents a known safe HTML document fragment that will be used by httpdoc as the source of documentation.

To understand the security risks involved with the use of this type, please read the documentation on the html/template.HTML type to which this type is converted verbatim by the httpdoc package.

type HTMLer 

type HTMLer interface {
	HTML() (HTML, error)
}

The HTMLer type returns an HTML value.

type SnippetType 

type SnippetType uint8
const (
	SNIPP_HTTP SnippetType = iota
	SNIPP_CURL
)

func (SnippetType) Lang 

func (st SnippetType) Lang() string

func (SnippetType) Name 

func (st SnippetType) Name() string

type TOC 

type TOC []*ArticleGroup

TOC is the input from which the documentation is generated.

type Value 

type Value interface{}

Value is a value that will be used by httpdoc as the source of documentation. Depending on the context in which it is used, different aspects of the value will be sourced to generate different kinds of documentation.

type Valuer 

type Valuer interface {
	Value() (Value, error)
}

The Valuer type returns a Value value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.