Document direct API spec references in docs.yml

[devin-ai-integration]

Summary

API reference navigation items in docs.yml can now point straight at OpenAPI, AsyncAPI, or GraphQL spec files via a new optional specs list on the api: item, instead of relying on the API being discovered through generators.yml. This matters for docs-only projects: the docs config owns its spec references and no generators.yml is needed. When specs is omitted, the existing api-name behaviour is unchanged.

Implements docs for: feat(docs): support direct API spec references (fern-api/fern#17749)

Field names (type, path, namespace, overlays, overrides) follow ApiSpecConfiguration in the source PR's docs.yml schema.

Pages changed:

• fern/products/docs/pages/api-references/generate-api-ref.mdx: new "Reference a spec directly from docs.yml" subsection with example and field list.
• fern/products/docs/pages/api-references/customize-api-ref.mdx: specs <ParamField> next to api-name.
• fern/products/docs/pages/api-references/generate-graphql-ref.mdx, generate-websocket-ref.mdx: one-line pointer for type: graphql / type: asyncapi.
• fern/products/docs/pages/changelog/2026-09-17.mdx: Docs changelog entry.

Vale and fern check --warnings pass (remaining warnings are pre-existing).

Link to Devin session: https://app.devin.ai/sessions/60634817a1d9468bb2ba97ca6d7def30
Open in Devin Desktop: https://app.devin.ai/desktop/session/60634817a1d9468bb2ba97ca6d7def30?variant=devin

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

📝 [vale] <FernStyles.Hyphens> _{reported by reviewdog 🐶}
'directly-from' doesn't need a hyphen.

Suggested change

API specification files to [load directly from docs.yml](/learn/docs/api-references/generate-api-ref#reference-a-spec-directly-from-docsyml) instead of through `generators.yml`. Each entry has a `type` (`openapi`, `asyncapi`, or `graphql`) and a `path`, plus optional `overrides`, `overlays`, and `namespace`. Paths are relative to the configuration file that contains them. When set, `api-name` is ignored.

API specification files to [load directly from docs.yml](/learn/docs/api-references/generate-api-ref#reference-a-spec-directly from-docsyml) instead of through `generators.yml`. Each entry has a `type` (`openapi`, `asyncapi`, or `graphql`) and a `path`, plus optional `overrides`, `overlays`, and `namespace`. Paths are relative to the configuration file that contains them. When set, `api-name` is ignored.

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1789664942-docs-yml-direct-specs.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/docs/api-references/customize-api-reference-layout
• learn/docs/api-references/generate-api-ref
• learn/docs/api-references/generate-graphql-ref
• learn/docs/api-references/generate-websocket-ref
• learn/docs/changelog/2026/9/17