(docs, api definitions) Document how to specify section display names in API Reference

fern/products/api-def/api-def.yml

@@ -58,6 +58,8 @@ navigation:
           - page: SDK method names
             path: ./openapi-pages/extensions/method-names.mdx
             slug: method-names
+          - page: Tag display names
+            path: ./openapi-pages/extensions/tag-display-name.mdx
           - page: Parameter names
             path: ./openapi-pages/extensions/parameter-names.mdx
           - page: Property names

fern/products/api-def/openapi-pages/extensions/overview.md

@@ -18,6 +18,7 @@ The table below shows all available extensions and links to detailed documentati
 | [`x-fern-bearer`](/api-definitions/openapi/authentication#bearer-security-scheme) | Customize bearer authentication parameter names and environment variables |
 | [`x-fern-availability`](./availability) | Mark availability status (beta, generally-available, deprecated) |
 | [`x-fern-base-path`](./base-path) | Set base path prepended to all endpoints |
+| [`x-displayName`](./tag-display-names) | Specify how tag names display in your API Reference |
 | [`x-fern-enum`](./enum-descriptions-and-names) | Add descriptions and custom names to enum values |
 | [`x-fern-examples`](./request-response-examples) | Associate request and response examples |
 | [`x-fern-global-headers`](./global-headers) | Configure headers used across all endpoints |

fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx

@@ -0,0 +1,20 @@
+---
+title: Tag display names
+description: Customize how tag names appear in your API Reference using the `x-displayName` extension
+---
+
+By default, tag names from your OpenAPI specification become section names in your API Reference. Use the `x-displayName` extension to control how these section names display in your generated documentation. This is helpful for controlling capitalization and creating user-friendly names. 
+
+You can set display names directly in your spec or in an overrides file.
+
+```yaml title="openapi.yml"
+tags:
+  - name: task
+    x-displayName: Tasks
+  - name: billing-and-payments
+    x-displayName: Billing and Payments
+```
+
+<Note>
+  Alternatively, you can rename sections directly in your [`docs.yml` file](/docs/api-references/customize-api-reference-layout).
+</Note>

fern/products/docs/pages/api-references/customize-api-ref.mdx

@@ -96,6 +96,30 @@ To reference an endpoint, you can use either:
 
 ## Customizing the API Reference
 
+### Renaming sections
+
+To override the display name of a section (created from tags in your API spec), 
+you can use the `section` property in your `docs.yml` and reference the original 
+tag name using `referenced-packages`.
+
+```yaml title="docs.yml" {4-6}
+navigation: 
+  - api: API Reference
+    layout:
+      - section: "User" # New display name
+        referenced-packages: 
+          - user-endpoint # Original tag name from your spec
+        contents: []
+      - section: "Plant"
+        referenced-packages: 
+          - plant
+        contents: []
+```
+<Note>
+  You can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension (OpenAPI)](/api-definitions/openapi/extensions/tag-display-names) or the [`display-name` parameter (Fern Definition)](/api-definitions/ferndef/endpoints/overview#display-name)
+</Note>
+
+
 ### Flattening sections
 To remove the API Reference title and display the section contents, set `flattened` to `true`.