Documenting an API

API Craft keeps documentation next to everything else: Markdown files in the project, committed and reviewed like the rest. You write prose; placeholders fill in the live details (parameters, examples, responses) from the spec, so the docs don't drift.

Where docs live

Docs attach at three levels:

  • API: apis/<api>/docs/index.md (plus extra pages docs/<name>.md).
  • Resource: apis/<api>/resources/<resource>/docs/index.md.
  • Operation: apis/<api>/resources/<resource>/docs/<operationName>.md (the file name matches the operation, e.g. get.md for Pet.get).

Author them in the app's Markdown editor (with live preview), or edit the files directly; both write the same files.

Frontmatter

Each file can carry YAML frontmatter:

---
title: Get a pet
order: 2
visibility: public
tags: [pet, lookup]
---

title sets the display title, order sorts siblings, visibility is public or private, and tags are free-form.

Pulling live data with placeholders

Write {{placeholder}} tokens and they're replaced at render time from the effective spec, so parameters and examples stay in sync with the API. A typical operation page:

---
title: Get a pet
---

# {{operation:title}}

Returns a single pet by its ID.

## Parameters
{{operation:parameters}}

## Example request
{{operation:requestExample}}

## Responses
{{operation:responses}}

Each placeholder is valid at a particular level: api:* in API docs, resource:* in resource docs, operation:* in operation docs. The full list is in the documentation file reference.

Linking between docs

Reference another API, resource, or operation with the apicraft:// scheme rather than a hard path:

See [the get operation](apicraft://api/petstore-api/resource/Pet/operation/get).

Each consumer resolves the link to its own navigation. (Translating these to plain HTML at documentation-export time isn't built yet; see the reference.)

What renders the docs

The app resolves placeholders for its live preview. A full documentation site export, assembling these files with the spec into a static site, is part of the export pipeline, which isn't built yet. For now, treat docs as the committed source of truth that the app renders.