v0.1.0OpenAPI 3.1.0

oaspect

Endpoints: 2
Groups: 1
Models: 4

Interactive API reference for OpenAPI documents. This page is rendered by oaspect itself from an OpenAPI document: the guide below is its info.description, and the Server helpers section documents the request contract of oaspect/server.

Install

Use	Install
Script tag	`<script src="https://cdn.jsdelivr.net/npm/oaspect" data-spec-url="/openapi.yaml"></script>`
React	`npm install @oaspect/react`
CLI	`npx oaspect build openapi.yaml -o docs.html`
Server helpers	`import { createProxyHandler, createSpecHandler } from "oaspect/server"`

Configuration

The same options work for Oaspect.init(target, options) and as <ApiReference> props.

Option	Default	Description
`spec` / `specUrl`	—	Document object, or URL of a JSON/YAML document
`title`, `logo`	`info.title`	Header branding
`locale`, `defaultLocale`, `onLocaleChange`	`"en"`	UI language
`messages`	—	Override UI strings or add languages
`proxyUrl`	`null`	Endpoint relaying "Try" requests (see below)
`features`	all on	`sourceMenu`, `languageSwitcher`, `themeToggle`, `tryIt`, `models`
`defaultSnippet`	`"shell:curl"`	Initial code sample
`storagePrefix`	`"oaspect"`	Prefix for saved preferences
`urlParam`	`"url"`	Query parameter loading another spec URL
`theme`	reader's choice	`"light"` or `"dark"`
`lazy`	`"auto"`	Render sections near the viewport only (above 40 operations)

Supported documents

OpenAPI 3.0 and 3.1, Swagger 2.0 (converted on load), JSON or YAML
External $refs to other files and URLs
Webhooks, callbacks, links, server variables, security schemes

Translating your documentation

Short fields use the x-i18n extension; Markdown fields can hold :::lang blocks, as this page does (switch the language in the header).

Server helpers

Web-standard Request → Response handlers from oaspect/server.

Relay a "Try" request

post/proxy

operationId: proxy

What the viewer posts to proxyUrl. createProxyHandler({ allowedHosts }) sends the request from the server and returns the response.

Request body

required

methodstring

Default: "GET"

Example: "POST"

urlstring<uri>required

headersobject

bodystring

Text body (JSON

array<FormPart>

multipart/form-data parts; files are base64-encoded.

Responses

statusinteger

Example: 200

statusTextstring

Example: "OK"

headersarray<array<string>>

bodystring

durationinteger

Milliseconds.

curl --request POST \
  --url 'https://docs.example.com/proxy' \
  --header 'Content-Type: application/json' \
  --data '{
  "method": "GET",
  "url": "https://api.example.com/pets?limit=10",
  "headers": {
    "Authorization": "Bearer token"
  }
}'

{
  "status": 200,
  "statusText": "OK",
  "headers": [
    [
      "string"
    ]
  ],
  "body": "string",
  "duration": 0
}

Serve the OpenAPI document

get/openapi

operationId: spec

createSpecHandler({ url, fallback }): fetches the live document server-side and caches it; serves the fallback when it cannot be reached.

Responses

Headers

x-oaspect-spec-sourcestring

remote, fallback (the viewer shows an out-of-date notice) or static.

Values:"remote""fallback""static"

object

Models

ProxyRequest

methodstring

Default: "GET"

Example: "POST"

urlstring<uri>required

headersobject

bodystring

Text body (JSON

array<FormPart>

multipart/form-data parts; files are base64-encoded.

FormPart

namestringrequired

valuestring

object

ProxyResponse

statusinteger

Example: 200

statusTextstring

Example: "OK"

headersarray<array<string>>

bodystring

durationinteger

Milliseconds.

Error

errorstring

Example: "api.internal is not an allowed host."