From 1310a1212c32b66ba570842b1dcc13293a6f4de7 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:09:23 +0000 Subject: [PATCH 1/2] docs: document types: true on api navigation item Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../api-references/customize-api-ref.mdx | 21 +++++++++++++++++++ .../api-references/generate-graphql-ref.mdx | 2 +- .../fern-instructions/docs/api-reference.mdx | 2 +- .../sdks/deep-dives/xml-encoded-types.mdx | 2 +- 4 files changed, 24 insertions(+), 3 deletions(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index d95afe6f03..4ebc9448be 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -207,6 +207,22 @@ navigation: `paginated` controls page layout only. It's unrelated to [endpoint pagination](/learn/api-definitions/openapi/extensions/pagination), which navigates through a response using cursors or offsets and requires no `docs.yml` configuration. +### Documenting standalone types + +By default, the API Reference only documents a schema inline on the pages of the endpoints, webhooks, and WebSockets that reference it. A schema that no operation references doesn't appear anywhere, so a spec whose value lives in its schemas (for example, a `paths: {}` document of XML element schemas, or shared models and event payloads never wired to an operation) renders nothing. Set `types` to `true` to give each of those schemas its own page. + +```yaml title="docs.yml" +navigation: + - api: API Reference + types: true +``` + +Fern adds a `Types` section as the last section of the API Reference, with one page per unreferenced schema sorted by title, at `/types/`. Schemas that an operation references, directly or through another schema, stay inline on that operation's page, and enums or objects declared inline inside another schema stay nested on their parent's page. + +Each type page lists the schema's properties, enum values, or union variants, and shows an example in the side panel. The example uses the schema's own `example` or `examples`, or is assembled from its properties' `example` values. Types with [XML encoding metadata](/learn/sdks/deep-dives/xml-encoded-types) (the OpenAPI `xml` object or `x-fern-xml-text`) get an XML example; all other types get a JSON example. Type pages are included in search, `llms.txt`, and the [Markdown version of each page](/learn/docs/ai-features/markdown). + +If the API Reference also includes a [GraphQL schema](/learn/docs/api-references/generate-graphql-ref#types), which has its own `Types` section, the standalone section is titled `Schemas` and lives at `/schemas/` instead. + ### Styling endpoints To customize the display of an endpoint, you can add a `title`. You can also use `slug` to customize the endpoint URL. @@ -497,6 +513,11 @@ The following properties can be set on the `- api` entry in your `docs.yml` navi + + When `true`, gives every schema that no endpoint, webhook, or WebSocket references [its own page](#documenting-standalone-types) under a `Types` section at the end of the API Reference. Defaults to `false`. + + + Settings for the [API Explorer](/learn/docs/api-references/api-explorer) that affect all endpoints in this API section. Can also be [set on individual sections or endpoints](#setting-api-explorer-options) in `layout` to override. diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index cccf60b7b5..4e4e50819d 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -118,4 +118,4 @@ The reference shows the client-facing schema: federation directives are stripped Fern generates a page for every named type in your schema, under a `Types` section at the root of the API Reference. Pages are grouped by kind: Objects, Inputs, Enums, Scalars, Interfaces, and Unions. Kinds your schema doesn't declare produce no group, and all GraphQL schemas in the API section share one `Types` section. -Type pages live at `/types//`, such as `/api-reference/types/objects/plant`. Interface pages also list the types that implement the interface. Types that only group operations, such as a `Mutation.plants: PlantMutations` namespace type, don't get a page. +Type pages live at `/types//`, such as `/api-reference/types/objects/plant`. Interface pages also list the types that implement the interface. Types that only group operations, such as a `Mutation.plants: PlantMutations` namespace type, don't get a page. When the same API Reference also sets [`types: true`](/learn/docs/api-references/customize-api-reference-layout#documenting-standalone-types) for its non-GraphQL schemas, those schema pages go in a separate `Schemas` section. diff --git a/fern/products/home/pages/fern-instructions/docs/api-reference.mdx b/fern/products/home/pages/fern-instructions/docs/api-reference.mdx index bf6177c8ad..2dabbdd9c0 100644 --- a/fern/products/home/pages/fern-instructions/docs/api-reference.mdx +++ b/fern/products/home/pages/fern-instructions/docs/api-reference.mdx @@ -28,7 +28,7 @@ Use this to add or change generated API Reference pages. ``` 3. Add `- api: API Reference` to navigation if it isn't there. With several APIs in separate folders, add one entry each with `api-name: `. -4. Adjust the layout on the `api` entry: order sections and endpoints, rename or flatten sections, paginate, hide endpoints, add overview pages, custom sections, pages and links. Use `audiences` to publish a subset of endpoints. +4. Adjust the layout on the `api` entry: order sections and endpoints, rename or flatten sections, paginate, hide endpoints, add overview pages, custom sections, pages and links. Use `audiences` to publish a subset of endpoints. Set `types: true` to give each schema that no endpoint, webhook or WebSocket references its own page (for schema-only specs such as XML element vocabularies). 5. Run `fern check` and review in `fern docs dev`. Use `--skip-api` to skip API pages when you're only editing prose. ## Rules diff --git a/fern/products/sdks/deep-dives/xml-encoded-types.mdx b/fern/products/sdks/deep-dives/xml-encoded-types.mdx index 152df6f77d..6eb923ceb4 100644 --- a/fern/products/sdks/deep-dives/xml-encoded-types.mdx +++ b/fern/products/sdks/deep-dives/xml-encoded-types.mdx @@ -5,7 +5,7 @@ description: Generate typed XML serializers, parsers, and fluent builders for ob Object types that carry XML encoding metadata are generated as XML-capable models. Each one gets a serializer, a parser, and fluent builder methods for its child elements, so SDK users build and read XML documents (for example, telephony markup such as TwiML) through typed code instead of hand-written strings. -Fern generates XML support in TypeScript, Python, Java, C#, Go, Ruby, and PHP SDKs. No SDK configuration is required: generation is driven entirely by the XML metadata in your API definition. Types without XML metadata are unchanged, and the XML runtime is only added to an SDK when an XML-encoded type references it. +Fern generates XML support in TypeScript, Python, Java, C#, Go, Ruby, and PHP SDKs. No SDK configuration is required: generation is driven entirely by the XML metadata in your API definition. Types without XML metadata are unchanged, and the XML runtime is only added to an SDK when an XML-encoded type references it. In Fern Docs, [standalone type pages](/learn/docs/api-references/customize-api-reference-layout#documenting-standalone-types) show an XML example for these types. ## Define types with XML metadata From 0dcb29c8a4af2d2f9151a7fd208c652f2fe037ba Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:08:38 +0000 Subject: [PATCH 2/2] docs: clarify type page schema examples (fern#18860, fern-platform#16172) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../api-references/customize-api-ref.mdx | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 4ebc9448be..6a026d5e09 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -219,7 +219,28 @@ navigation: Fern adds a `Types` section as the last section of the API Reference, with one page per unreferenced schema sorted by title, at `/types/`. Schemas that an operation references, directly or through another schema, stay inline on that operation's page, and enums or objects declared inline inside another schema stay nested on their parent's page. -Each type page lists the schema's properties, enum values, or union variants, and shows an example in the side panel. The example uses the schema's own `example` or `examples`, or is assembled from its properties' `example` values. Types with [XML encoding metadata](/learn/sdks/deep-dives/xml-encoded-types) (the OpenAPI `xml` object or `x-fern-xml-text`) get an XML example; all other types get a JSON example. Type pages are included in search, `llms.txt`, and the [Markdown version of each page](/learn/docs/ai-features/markdown). +Each type page lists the schema's properties, enum values, or union variants, and shows an example in the side panel. For an OpenAPI object schema, the example is the schema's first `example` or `examples` entry. A schema without one gets an example assembled from its properties' `example` values, but only when every required property has an `example`. Otherwise, the example uses placeholder values. + +```yaml title="openapi.yml" +components: + schemas: + Say: + type: object + xml: + name: Say + properties: + voice: + type: string + xml: + attribute: true + message: + type: string + example: + voice: alice + message: Thanks for calling. +``` + +Types with [XML encoding metadata](/learn/sdks/deep-dives/xml-encoded-types) (the OpenAPI `xml` object or `x-fern-xml-text`) get an XML example; all other types get a JSON example. An XML example built from a schema example writes only the properties the example sets and one element per list item, rendering each item of a `oneOf` list as the variant it matches. Type pages are included in search, `llms.txt`, and the [Markdown version of each page](/learn/docs/ai-features/markdown). If the API Reference also includes a [GraphQL schema](/learn/docs/api-references/generate-graphql-ref#types), which has its own `Types` section, the standalone section is titled `Schemas` and lives at `/schemas/` instead.