API reference pages

An API reference page is a Markdown page with an api front matter key. The key names a spec file and one operation or object in that spec. Bark renders the endpoint, authorizations, parameters, body, responses, request samples, response examples and a playground.

---
api: openapi.yaml POST /tasks/{taskId}
---

Markdown below the front matter renders under the operation description.

Front matter ​

The spec file path is relative to the page. A leading / resolves the path from the docs root. The file must be inside the docs folder. URLs are rejected.

Spec formats ​

api: openapi.yaml QUERY /tasks          # OpenAPI 3.2 QUERY method
api: openapi.yaml PURGE /cache          # OpenAPI 3.2 additionalOperations
api: openapi.yaml webhook taskProcessed # webhook payload, no playground
api: openapi.yaml schema FileData       # object page
api: schema.graphql query country
api: metadata.xml GET People(key)       # renders as /People({UserName})
api: metadata.xml POST ResetDataSource  # action import

OpenAPI ​

• Methods: GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE, QUERY, and custom methods defined in additionalOperations.
• Parameter locations: path, query, querystring, header, cookie. Parameters defined with content read the schema of the first media type.
• $ref resolves within the same document. allOf merges into one attribute list. oneOf and anyOf list the variant types and expand the first variant.
• itemSchema describes each item of a sequential media type (JSON Lines, server-sent events).
• Request bodies exclude readOnly properties. Responses exclude writeOnly properties.
• Examples are read from example, examples, default and enum. Missing examples are generated from the schema.

GraphQL ​

• Arguments render as the Arguments section and as request variables.
• The request sample selects scalar and enum fields to a depth of 2. Fields with required arguments are excluded from the selection.
• subscription operations are documented without a playground.

OData ​

Properties annotated Core.Computed or Core.Immutable are read-only. Descriptions are read from Core.Description annotations.

API sections ​

An API section is a folder generated from one spec file. The folder index page sets apiSpec:

---
title: Example API
apiSpec: openapi.yaml
---

Bark generates one page per operation and object, and a sidebar for the folder. The index page is the first sidebar entry.

• A Markdown file with the same slug replaces the generated page. Example: update-task.md with api: openapi.yaml POST /tasks/{id} adds Markdown to that operation.
• A sidebar key in config.json for the same folder replaces the generated sidebar.
• Generated pages link Edit this page to the spec file.
• Group names are translatable in the locale files (apiGroupEndpoints, apiGroupObjects and related keys).

Navigation ​

Single API pages use the standard sidebar configuration. A sidebar key with a path prefix assigns a separate menu to every page under that folder. Nested groups define namespaces.

{
  "sidebar": {
    "/api/": [
      {
        "title": "Tasks",
        "items": [
          { "title": "Get task", "path": "api/get-task" },
          { "title": "Update task", "path": "api/update-task" }
        ]
      }
    ]
  }
}

Sidebar entries for API operation pages display the HTTP method. See Sidebar for prefix matching and collapsible groups.

Page layout ​

Nested attributes are collapsed under Show child attributes. API pages have no table of contents. Below 1100px, the side column renders below the main column.

Playground ​

Try it opens the playground. The left column contains inputs for authorizations, parameters and the body. The right column displays the example responses, then the live response: status, duration, size, body and headers.

• Requests are sent from the reader's browser to the API. Bark does not send or forward requests.
• Browser cookies are not sent.
• Credentials and playground input are kept in memory only. Nothing is written to browser storage. Reloading or leaving the page clears them.
• Requests are limited to the spec servers or the server URL.
• The API must allow cross-origin requests (CORS) from the docs site, including every documented method, such as QUERY.
• Cookie parameters and cookie API keys are not sent. Browsers block the Cookie header.
• JSON and text bodies use one text field. Form bodies (multipart/form-data, application/x-www-form-urlencoded) use one input per attribute and a file picker for binary attributes.

Localization ​

Section headings, badges and playground labels are translatable in the locale files. The keys start with api, for example apiTryIt and apiSend.

Errors ​

If the specification file, the selector or the content is invalid: the page displays the error above the page Markdown. The error is also written to the log.