module.go

package expose

import (
	"slices"

	"github.com/getkin/kin-openapi/openapi3"
)

// ModuleDoc documents a path section ("module") of the api.
type ModuleDoc struct {
	// Path is the path prefix of the module, e.g. "/guestlist"
	Path string
	// Description documents all endpoints below Path. It may contain markdown.
	Description string
}

// ModuleDocumenter is implemented by [Function] values that carry
// documentation for the module(s) they belong to. [ReflectSpec] registers
// these docs as tag descriptions in the spec, where they are rendered as
// group headers by swagger ui and picked up by the discovery filter
// [FilterSpec] as the description of collapsed path groups.
type ModuleDocumenter interface {
	ModuleDocs() []ModuleDoc
}

// Module attaches a description to all provided functions, documenting the
// path section they live under. This keeps the documentation colocated with
// the route definitions:
//
//	expose.Module("/guestlist", "How the guest list works ...",
//		expose.Func("/guestlist/add", Add),
//		expose.Func("/guestlist/remove", Remove),
//	)
//
// The description ends up as the tag description of the module in the openapi
// spec and as the description of the collapsed group in the discovery view
// (see [FilterSpec]). Structs registered with [Struct] can provide their
// module description by implementing `ModuleDoc() string` instead.
func Module(pathPrefix string, description string, fns ...Function) []Function {
	doc := ModuleDoc{Path: normalizePrefix(pathPrefix), Description: description}
	wrapped := make([]Function, len(fns))
	for i, fn := range fns {
		wrapped[i] = &moduleFunction{Function: fn, doc: doc}
	}
	return wrapped
}

// moduleFunction wraps a [Function] with the documentation of its module.
type moduleFunction struct {
	Function
	doc ModuleDoc
}

func (fn *moduleFunction) ModuleDocs() []ModuleDoc {
	docs := []ModuleDoc{fn.doc}
	if inner, ok := fn.Function.(ModuleDocumenter); ok {
		docs = append(docs, inner.ModuleDocs()...)
	}
	return docs
}

// AnnotateOperation forwards to the wrapped function, since embedding does
// not promote the optional [OperationAnnotator] interface.
func (fn *moduleFunction) AnnotateOperation(op *openapi3.Operation) {
	if annotator, ok := fn.Function.(OperationAnnotator); ok {
		annotator.AnnotateOperation(op)
	}
}

// upsertTag returns the tags with the description of the named tag set,
// appending a new tag when the name is not present yet. Existing tags are
// replaced by copies, so shared tag values (e.g. from a user provided default
// spec) are never mutated.
func upsertTag(tags openapi3.Tags, name string, description string) openapi3.Tags {
	for i, tag := range tags {
		if tag.Name != name {
			continue
		}
		replaced := *tag
		replaced.Description = description
		result := slices.Clone(tags)
		result[i] = &replaced
		return result
	}
	// clone before appending: the provided tags may share their backing array
	// with a caller owned slice (e.g. the default spec), which a plain append
	// could write into when there is spare capacity
	return append(slices.Clone(tags), &openapi3.Tag{Name: name, Description: description})
}

// fallbackDescription wraps a [Function] and sets the description of its
// operation, unless the operation already provides one.
type fallbackDescription struct {
	Function
	description string
}

func (fn *fallbackDescription) AnnotateOperation(op *openapi3.Operation) {
	if annotator, ok := fn.Function.(OperationAnnotator); ok {
		annotator.AnnotateOperation(op)
	}
	if op.Description == "" {
		op.Description = fn.description
	}
}