apidoc

apidoc

import "github.com/brpaz/lib-go/apidoc"

Package apidoc provides an HTTP handler for serving OpenAPI documentation.

It exposes two routes:

• GET /openapi.yml — raw OpenAPI spec (always enabled)
• GET / — Scalar UI (opt-in via WithScalarUI)

Basic usage

spec, _ := os.ReadFile("openapi.yml")

h, err := apidoc.New(
    apidoc.WithSpec(spec),
    apidoc.WithScalarUI(),
)
if err != nil {
    log.Fatal(err)
}

// Mount under a prefix with chi:
r.Mount("/docs", h)

// Or with stdlib:
http.Handle("/docs/", http.StripPrefix("/docs", h))

Index

• type Handler
  • func New(opts ...Option) (*Handler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Option
  • func WithScalarUI() Option
  • func WithSpec(spec []byte) Option

type Handler

Handler serves OpenAPI documentation. It implements [http.Handler] and is intended to be mounted at a path prefix (e.g. chi's router.Mount or http.StripPrefix + http.Handle).

GET /             → Scalar UI (requires [WithScalarUI])
GET /openapi.yml  → raw YAML spec

type Handler struct {
    // contains filtered or unexported fields
}

func New

func New(opts ...Option) (*Handler, error)

New creates a new Handler and validates required options.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Option

Option configures a Handler.

type Option func(*Handler)

func WithScalarUI

func WithScalarUI() Option

WithScalarUI enables the Scalar UI route at the handler root.

func WithSpec

func WithSpec(spec []byte) Option

WithSpec sets the raw OpenAPI spec bytes to serve.

Generated by gomarkdoc