docs

Documentation

Index

• func DocTags(tags ...string) *[]string
• type DocGroup
• type DocOperation
• type DocParameters
• type DocPayload
  • func DocJsonPayload[T any](description ...string) DocPayload
  • func DocText(description ...string) DocPayload
  • func DocXmlPayload[T any](description ...string) DocPayload
• type DocResponses
• type DocRoute
• type DocViewerHandler
• type DocViewerSources
• type IDocViewer
  • func VoidViewer() IDocViewer
• type MediaType
• type ParameterType

Functions

func DocTags

func DocTags(tags ...string) *[]string

DocTags creates a pointer to a slice of tags for route grouping.

Types

type DocGroup

type DocGroup struct {
	Headers   DocParameters
	Cookies   DocParameters
	Responses DocResponses
}

DocGroup represents a group of routes sharing headers, cookies, or response types.

type DocOperation

type DocOperation struct {
	Description string
	Method      string
	BasePath    string
	Path        string
	Parameters  DocParameters
	Query       DocParameters
	Files       DocParameters
	Cookies     DocParameters
	Request     DocPayload
	Responses   DocResponses
	Tags        *[]string
}

DocOperation represents a documented API operation, combining route info and documentation.

type DocParameters

type DocParameters map[string]string

DocParameters maps parameter names to their description.

type DocPayload

type DocPayload struct {
	Payload     any
	MediaType   MediaType
	Description string
}

DocPayload represents a request or response body and its metadata.

func DocJsonPayload

func DocJsonPayload[T any](description ...string) DocPayload

DocJsonPayload creates a DocPayload with JSON media type.

func DocText

func DocText(description ...string) DocPayload

DocText creates a DocPayload representing text or empty JSON body.

func DocXmlPayload

func DocXmlPayload[T any](description ...string) DocPayload

DocXmlPayload creates a DocPayload with XML media type.

type DocResponses

type DocResponses map[string]DocPayload

DocResponses maps HTTP status codes or response identifiers to DocPayloads.

type DocRoute

type DocRoute struct {
	Description string
	Parameters  DocParameters
	Query       DocParameters
	Files       DocParameters
	Cookies     DocParameters
	Request     DocPayload
	Responses   DocResponses
	Tags        *[]string
}

DocRoute represents the documentation for a single route.

type DocViewerHandler

type DocViewerHandler struct {
	Method      string
	Route       string
	Handler     handler
	Name        string
	Description string
}

DocViewerHandler describes a single documentation handler.

type DocViewerSources

type DocViewerSources struct {
	Name        string `json:"name"`
	Route       string `json:"route"`
	Description string `json:"description"`
}

DocViewerSources represents a documented source route.

type IDocViewer

type IDocViewer interface {
	// Handlers returns a list of handlers that expose the documentation endpoints.
	Handlers() []DocViewerHandler
	// RegisterGroup registers a route group and its associated documentation.
	RegisterGroup(group string, data DocGroup) IDocViewer
	// RegisterRoute registers a single route operation and its documentation.
	RegisterRoute(route DocOperation) IDocViewer
}

IDocViewer defines an interface for a documentation viewer.

func VoidViewer

func VoidViewer() IDocViewer

VoidViewer creates and returns a no-op documentation viewer.

Use this when you want to disable route documentation while keeping the Router’s DocViewer interface satisfied.

type MediaType

type MediaType string

MediaType defines the MIME type of a request or response payload.

const (
	JSON MediaType = "application/json"
	XML  MediaType = "application/xml"
)

type ParameterType

type ParameterType string

ParameterType defines the location type of a request parameter.

const (
	QUERY ParameterType = "query"
	PATH  ParameterType = "path"
)