# modules/openapi/reference

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

Package reference renders an OpenAPI 3.1 document as an API reference in the apistock design (ADR-0049): an overview, and a page per operation with its parameters, responses, request examples in curl, Go and TypeScript, response examples and "Try it". Generated apps serve it at /docs through openapi.MountDocs, and apistock.dev renders its example API with it, so the two look the same.

Pages load nothing from other origins: the stylesheet, scripts and fonts come from [Assets](#Assets), and [Reference.Handler](#Reference.Handler) serves them under [ContentSecurityPolicy](#ContentSecurityPolicy).

Stability: pre-1.0 (ADR-0015).

## Constants

### const ContentSecurityPolicy

```go
const ContentSecurityPolicy = "default-src 'none'; script-src 'self'; style-src 'self'; font-src 'self'; " +
	"img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
```

ContentSecurityPolicy is the policy [Reference.Handler](#Reference.Handler) sends with every page: the reference's own scripts, styles and fonts, and requests only to the API serving it.

## Functions

### func LLMs

```go
func LLMs(doc []byte, opts ExportOptions) ([]byte, error)
```

LLMs returns llms.txt ([https://llmstxt.org](https://llmstxt.org)) for doc, an OpenAPI 3.1 document in JSON: the API's name and summary, how to authenticate, and every endpoint by tag, linked to its Markdown page in the reference the app serves (ADR-0051). The output is deterministic.

### func Postman

```go
func Postman(doc []byte, opts ExportOptions) ([]byte, error)
```

Postman returns a Postman collection (format v2.1) for doc, an OpenAPI 3.1 document in JSON: a folder per tag, {{baseUrl}} and {{token}} variables, bearer authentication on operations that declare security, and example bodies built from the schemas (ADR-0051). The output is deterministic, so a committed collection changes only when the API does.

## Types

### type AssetFile

```go
type AssetFile struct {
	// Name is the file name to serve, relative to the assets directory. The
	// stylesheet and scripts carry a content hash, so they can be cached
	// forever; fonts keep their names, which the stylesheet refers to.
	Name string
	// Source is the name layouts ask for, such as "reference.css".
	Source string
	Data   []byte
}
```

AssetFile is a file reference pages load: the stylesheet, a script, or a font with its licence.

#### func Assets

```go
func Assets() []AssetFile
```

Assets returns the stylesheet (reference.css), scripts (reference.js and theme.js, which applies the reader's theme before the page paints) and fonts reference pages use, for sites that put pages in their own layout. Serve them from one directory.

### type ExportOptions

```go
type ExportOptions struct {
	// BaseURL is the API's address, the collection's baseUrl variable.
	// Default: http://localhost:8080.
	BaseURL string
	// DocsPath is where the app serves this reference, for llms.txt links.
	// Default: /docs.
	DocsPath string
}
```

ExportOptions configure [Postman](#Postman) and [LLMs](#LLMs).

### type Heading

```go
type Heading struct {
	ID, Text string
	Level    int
}
```

Heading is a section of a page.

### type Options

```go
type Options struct {
	// Title names the API in headers and on the overview. Default: the
	// document's info.title.
	Title string
	// Intro is Markdown shown at the top of the overview. Default: the
	// document's info.description.
	Intro string
	// BasePath is where the pages are served. Default "/docs".
	BasePath string
	// TrailingSlash ends page URLs with a slash, for static hosts that serve
	// directories.
	TrailingSlash bool
	// SameOrigin says the pages are served by the API they document: "Try
	// it" sends requests to the page's own origin with the browser's cookies.
	// Otherwise readers choose the server, and cookies aren't sent.
	SameOrigin bool
	// SpecURL, when set, is linked from standalone pages.
	SpecURL string
}
```

Options configure [Build](#Build).

### type Page

```go
type Page struct {
	URL   string
	Title string
	// Tag groups operations in navigation; "Overview" for the overview.
	Tag string
	// Method and Path are empty on the overview.
	Method, Path string
	// Description is plain text for meta tags and search.
	Description string
	// Main is the page's content. Panel holds an operation's examples and
	// "Try it", shown beside it; it is empty on the overview.
	Main, Panel template.HTML
	// TOC lists the overview's sections.
	TOC []Heading
	// Markdown is the page as Markdown, served next to it with .md.
	Markdown string
	// Text is the page's words, for search.
	Text string
}
```

Page is one page of a reference. Main and Panel are HTML fragments for a layout: the standalone pages of [Reference.Handler](#Reference.Handler), or a site's own.

### type Reference

```go
type Reference struct {
	// Title names the API.
	Title string
	// Version is the document's info.version.
	Version string
	// Pages are the overview, then a page per operation grouped by tag.
	Pages []*Page
	// contains filtered or unexported fields
}
```

Reference is a rendered API reference.

#### func Build

```go
func Build(doc []byte, opts Options) (*Reference, error)
```

Build renders doc, an OpenAPI 3.1 document in JSON.

#### func (*Reference) Handler

```go
func (r *Reference) Handler() (http.Handler, error)
```

Handler returns a handler serving the reference at its base path as standalone pages: every page, its Markdown at .md, search.json, the assets under assets/, and a 404 page, all under [ContentSecurityPolicy](#ContentSecurityPolicy). Pages are rendered once, here.

#### func (*Reference) SearchIndex

```go
func (r *Reference) SearchIndex() ([]byte, error)
```

SearchIndex returns the index the search dialog loads: a JSON array of pages with their titles, sections, URLs, methods, paths and text.