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 d95afe6f0..6a026d5e0 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,43 @@ 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. 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. + ### 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 +534,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 cccf60b7b..4e4e50819 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 bf6177c8a..2dabbdd9c 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 152df6f77..6eb923ceb 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