A reference to the human readable documentation for an API, that describes the surface area of an API with all the details consumers need. This documentation may or may not be generated from an OpenAPI or other machine-readable artifact, but is published as HTML or Markdown, and mean for human consumption when onboarding with an API.

Also known as: Docs, API Reference, Developer Documentation, Reference

Example

- type: Documentation
  url: https://developers.example.com/docs

Standards

• OpenAPI Initiative OpenAPI Specification 3.1
• OpenAPI Initiative OpenAPI Specification 3.0
• AsyncAPI Initiative AsyncAPI 3.0
• IETF (draft) JSON Schema 2020-12
• IETF RFC 9727 — api-catalog Well-Known URI
• CommonMark CommonMark 0.31
• GraphQL Foundation GraphQL — June 2018 Specification
• Schema.org Schema.org APIReference

HTTP Headers

Well-Known Paths

• /.well-known/api-catalog — RFC 9727 — Discoverable catalog of an organization's APIs and their documentation.

Media Types

• text/html — Canonical rendered documentation format.
• text/markdown — RFC 7763
• application/vnd.oai.openapi — OpenAPI document (YAML form).
• application/vnd.oai.openapi+json — OpenAPI document (JSON form).

OpenAPI Expression

• info.description (OpenAPI 3.x) — Long-form Markdown description shown at the top of generated reference docs.
• info.summary (OpenAPI 3.1) — Short description of the API.
• info.termsOfService (OpenAPI 3.x)
• externalDocs (OpenAPI 3.x) — Pointer to additional human documentation (URL + description).
• tags[].description (OpenAPI 3.x) — Per-tag prose used to group operations in rendered docs.
• tags[].externalDocs (OpenAPI 3.x)
• operation.description (OpenAPI 3.x) — Per-operation Markdown rendered as the body of each endpoint section.

Link Relations

• service-doc — IANA Link Relations
• describedby — RFC 8288
• service-desc — IANA Link Relations

Governance Rules

• info-description (Spectral built-in) — `info.description` must be present and non-empty.
• info-contact (Spectral built-in) — `info.contact` must be defined so readers can reach the maintainers.
• oas-tag-description (Spectral built-in) — Every tag must have a description.
• operation-description (Spectral built-in) — Every operation must have a description.
• operation-tag-defined (Spectral built-in) — Operation tags must be declared at the document level (with descriptions).

Risk & Compliance

Compliance:

• WCAG 2.2 — documentation sites are user-facing and subject to accessibility requirements
• Export controls — cryptography-related docs may require classification review

Security: Documentation often leaks sensitive details — internal hostnames, example tokens, unredacted PII in samples, or undocumented but discoverable endpoints. Treat docs as a publication surface; review samples for secrets and keep internal-only operations out of public bundles.

Tools

• Redocly — Docs generator
• Stoplight Elements — Docs generator (Apache-2.0)
• Mintlify — Docs platform
• Bump.sh — Docs and change tracking
• Scalar — Docs generator (MIT)
• ReadMe — Docs platform

Suggested Metrics

• docs_coverage — Share of operations with non-empty descriptions and at least one example.
• time_to_first_doc_view — Median time from signup to first documentation page view.
• search_zero_results_rate — Fraction of in-docs searches that return no results — proxy for content gaps.
• stale_pages — Count of pages whose last-modified date trails the latest spec revision.

Example Implementations

• Stripe — Three-column reference docs generated from internal spec with side-by-side code samples.
• Twilio — Multi-product docs site with versioned reference and tutorials.
• GitHub — REST and GraphQL reference generated from the public OpenAPI description.
• Plaid — Narrative docs interleaved with reference, common in financial-data APIs.

Related Properties

• Openapi
• Getting started
• Software development kits
• Change log
• Tutorials

Tags

• Onboarding
• Documentation
• Information

All Common Properties