# modules/openapi

```go
import "apistock.dev/modules/openapi"
```

Package openapi integrates Huma with apistock (ADR-0027): an API on the standard http.ServeMux, problem+json errors produced by the application's error mapper, an API reference at /docs in the apistock design (ADR-0049, rendered by package reference), and OpenAPI export.

Huma is used only in delivery layers and the composition root of generated apps; domain, use case and repository code never imports it.

Stability: pre-1.0 (ADR-0015).

## Constants

### const BearerScheme

```go
const BearerScheme = "bearer"
```

BearerScheme is the name of the bearer security scheme.

## Variables

### var Bearer

```go
var Bearer = []map[string][]string{{BearerScheme: {}}}
```

Bearer is the security requirement for operations that need a session token. Use it as huma.Operation.Security.

## Functions

### func InstallErrors

```go
func InstallErrors(mapper *httpx.Mapper)
```

InstallErrors makes every Huma error an [httpx.Problem](/reference/httpx/#Problem):

  - errors matched by mapper (domain sentinels, \*httpx.Problem) use their mapping;
  - validation and other client errors keep their status, get the default code (for example "validation\_failed") and list field errors without echoing submitted values;
  - server errors become a generic 500 and are logged once by mapper.

Huma stores these hooks in package-level variables, so call InstallErrors once, from the composition root, before registering operations. It is the only package-level state an apistock app changes (ADR-0027).

### func MountDocs

```go
func MountDocs(mux *http.ServeMux, opts DocsOptions)
```

MountDocs serves an API reference for the API on mux at opts.Path, in the apistock design (ADR-0049): an overview, a page per operation with its parameters, responses, request examples and "Try it", and search.

The pages are rendered from the OpenAPI document that mux serves at opts.SpecURL, read in-process on the first request, so every operation registered before the server starts appears without further setup. Styles, scripts and fonts are served by the app itself under [reference.ContentSecurityPolicy](/reference/modules/openapi/reference/#ContentSecurityPolicy); the pages make no external requests.

### func New

```go
func New(mux *http.ServeMux, title, version string, opts ...Option) huma.API
```

New returns a Huma API registered on mux. It serves the OpenAPI document at /openapi.json and /openapi.yaml, disables Huma's built-in docs (use [MountDocs](#MountDocs)) and response $schema links, and doesn't expose /schemas.

Call [InstallErrors](#InstallErrors) before registering operations.

### func WriteSpec

```go
func WriteSpec(w io.Writer, api huma.API) error
```

WriteSpec writes api's OpenAPI document to w as indented JSON. Generated apps call it from "my-api openapi" to export api/openapi.json.

## Types

### type DocsOptions

```go
type DocsOptions struct {
	Path    string // default "/docs"
	SpecURL string // default "/openapi.json", served by the same mux
	Title   string // default "API Reference"
}
```

DocsOptions configure [MountDocs](#MountDocs).

### type Option

```go
type Option interface {
	// contains filtered or unexported methods
}
```

An Option configures [New](#New).

#### func WithBearerAuth

```go
func WithBearerAuth(description string) Option
```

WithBearerAuth declares the bearer security scheme used by [Bearer](#Bearer).

#### func WithDescription

```go
func WithDescription(markdown string) Option
```

WithDescription sets the API description shown in the docs.