Documentation
¶
Overview ¶
Package docs registers stable API documentation and OpenAPI endpoints.
Without a registered provider, the default manager discovers OpenAPI files from fixed relative paths under the service working directory, such as ./swagger/openapi.json and ./docs/openapi.json. Production services should prefer RegisterProvider when the OpenAPI source is known at wiring time.
Custom docs managers can expose HTML-mode-specific handler behavior by implementing HTMLModeProvider in addition to ManagerContract. These package-local aliases remain exactly source-compatible with their root ports counterparts during v3.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/endpoints/docs`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- type Config
- type HTMLMode
- type HTMLModeProvider
- type Handler
- func (h *Handler) HTMLHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handler) InfoHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handler) Middleware() func(http.Handler) http.Handler
- func (h *Handler) OpenAPIHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handler) RegisterCustomRoutes(router interface{ ... }, paths Paths)
- func (h *Handler) RegisterCustomRoutesTo(router RouteRegistrar, paths Paths)
- func (h *Handler) RegisterRoutes(router interface{ ... })
- func (h *Handler) RegisterRoutesTo(router RouteRegistrar)
- func (h *Handler) VersionHandler(w http.ResponseWriter, r *http.Request)
- type Info
- type Manager
- func (m *Manager) GetHTML() (string, error)
- func (m *Manager) GetInfo() Info
- func (m *Manager) GetOpenAPI() ([]byte, error)
- func (m *Manager) GetVersion() (string, error)
- func (m *Manager) HTMLMode() HTMLMode
- func (m *Manager) RegisterProvider(provider Provider)
- func (m *Manager) ServeHTML(w http.ResponseWriter, _ *http.Request)
- func (m *Manager) ServeInfo(w http.ResponseWriter, _ *http.Request)
- func (m *Manager) ServeOpenAPI(w http.ResponseWriter, _ *http.Request)
- func (m *Manager) ServeVersion(w http.ResponseWriter, _ *http.Request)
- type ManagerContract
- type Paths
- type Provider
- type RouteRegistrar
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Title string `json:"title"`
Description string `json:"description"`
Version string `json:"version"`
Contact string `json:"contact,omitempty"`
License string `json:"license,omitempty"`
Paths Paths `json:"paths"`
EnableHTML bool `json:"enable_html"`
EnableJSON bool `json:"enable_json"`
EnableYAML bool `json:"enable_yaml"`
HTMLMode HTMLMode `json:"html_mode,omitempty"`
}
Config defines documentation endpoint configuration.
type HTMLMode ¶
type HTMLMode string
HTMLMode controls the HTML presentation mode for the docs surface.
type HTMLModeProvider ¶
type HTMLModeProvider interface {
HTMLMode() HTMLMode
}
HTMLModeProvider exposes a manager's configured HTML rendering mode.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler provides HTTP handlers for documentation endpoints.
func NewDefaultHandler ¶
func NewDefaultHandler() *Handler
NewDefaultHandler builds a handler using the default docs manager.
func NewHandler ¶
func NewHandler(manager ManagerContract) *Handler
NewHandler creates a new docs handler.
func (*Handler) HTMLHandler ¶
func (h *Handler) HTMLHandler(w http.ResponseWriter, r *http.Request)
HTMLHandler handles HTML documentation requests. @Summary API Documentation @Description Returns the API documentation page @Tags docs @Accept html @Produce html @Success 200 {string} string "HTML documentation page" @Router /docs [get]
func (*Handler) InfoHandler ¶
func (h *Handler) InfoHandler(w http.ResponseWriter, r *http.Request)
InfoHandler handles info requests.
func (*Handler) Middleware ¶
Middleware creates a middleware that adds documentation information to requests.
func (*Handler) OpenAPIHandler ¶
func (h *Handler) OpenAPIHandler(w http.ResponseWriter, r *http.Request)
OpenAPIHandler handles OpenAPI specification requests. @Summary OpenAPI Specification @Description Returns the configured OpenAPI specification when the docs surface is enabled @Tags docs @Accept json @Produce json @Success 200 {object} map[string]interface{} "OpenAPI specification" @Failure 404 {object} map[string]interface{} "OpenAPI specification disabled or not found" @Router /docs/openapi.json [get]
func (*Handler) RegisterCustomRoutes ¶
func (h *Handler) RegisterCustomRoutes(router interface { Get(pattern string, h http.HandlerFunc) }, paths Paths)
RegisterCustomRoutes registers documentation endpoints with custom paths.
func (*Handler) RegisterCustomRoutesTo ¶
func (h *Handler) RegisterCustomRoutesTo(router RouteRegistrar, paths Paths)
RegisterCustomRoutesTo registers documentation endpoints with custom paths.
func (*Handler) RegisterRoutes ¶
func (h *Handler) RegisterRoutes(router interface { Get(pattern string, h http.HandlerFunc) })
RegisterRoutes registers all documentation endpoints on the given router.
func (*Handler) RegisterRoutesTo ¶
func (h *Handler) RegisterRoutesTo(router RouteRegistrar)
RegisterRoutesTo registers all documentation endpoints on the given registrar.
func (*Handler) VersionHandler ¶
func (h *Handler) VersionHandler(w http.ResponseWriter, r *http.Request)
VersionHandler handles version requests.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager implements ManagerContract for managing documentation.
func (*Manager) GetOpenAPI ¶
GetOpenAPI returns the OpenAPI specification.
func (*Manager) GetVersion ¶
GetVersion returns the API version.
func (*Manager) RegisterProvider ¶
RegisterProvider registers a documentation provider.
func (*Manager) ServeHTML ¶
func (m *Manager) ServeHTML(w http.ResponseWriter, _ *http.Request)
ServeHTML serves the HTML documentation.
func (*Manager) ServeInfo ¶
func (m *Manager) ServeInfo(w http.ResponseWriter, _ *http.Request)
ServeInfo serves the documentation info.
func (*Manager) ServeOpenAPI ¶
func (m *Manager) ServeOpenAPI(w http.ResponseWriter, _ *http.Request)
ServeOpenAPI serves the OpenAPI specification.
func (*Manager) ServeVersion ¶
func (m *Manager) ServeVersion(w http.ResponseWriter, _ *http.Request)
ServeVersion serves the API version.
type ManagerContract ¶
type ManagerContract interface {
RegisterProvider(provider Provider)
GetHTML() (string, error)
GetOpenAPI() ([]byte, error)
GetVersion() (string, error)
GetInfo() Info
ServeHTML(w http.ResponseWriter, r *http.Request)
ServeOpenAPI(w http.ResponseWriter, r *http.Request)
ServeVersion(w http.ResponseWriter, r *http.Request)
ServeInfo(w http.ResponseWriter, r *http.Request)
}
ManagerContract defines the package-local documentation manager contract.
func NewStrict ¶
func NewStrict() ManagerContract
NewStrict creates a docs manager that avoids third-party assets in HTML mode.
func NewSwaggerUI ¶
func NewSwaggerUI() ManagerContract
NewSwaggerUI creates a docs manager that opts into the CDN-backed Swagger UI surface.
func NewWithConfig ¶
func NewWithConfig(config Config) ManagerContract
NewWithConfig creates a new docs manager with custom configuration.
Example ¶
package main
import (
"fmt"
docsendpoint "github.com/aatuh/api-toolkit/v4/endpoints/docs"
)
func main() {
manager := docsendpoint.NewWithConfig(docsendpoint.Config{
Title: "Widget API",
Version: "1.0.0",
EnableHTML: true,
EnableJSON: false,
})
info := manager.GetInfo()
fmt.Println(info.Title)
fmt.Println(info.Version)
}
Output: Widget API 1.0.0
type Paths ¶
type Paths struct {
HTML string `json:"html"`
OpenAPI string `json:"openapi"`
Version string `json:"version"`
Info string `json:"info"`
}
Paths defines the paths for documentation endpoints.
func DefaultPaths ¶
func DefaultPaths() Paths
DefaultPaths returns the default documentation endpoint paths.
type Provider ¶
type Provider interface {
GetHTML() (string, error)
GetOpenAPI() ([]byte, error)
GetVersion() (string, error)
GetInfo() Info
}
Provider defines the package-local documentation content contract.
type RouteRegistrar ¶
type RouteRegistrar interface {
Get(pattern string, h http.HandlerFunc)
}
RouteRegistrar is the minimal documentation route registration contract.
Source Files