diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml
index 16ec2b7c6..5cd08e799 100644
--- a/fern/products/api-def/api-def.yml
+++ b/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
diff --git a/fern/products/api-def/ferndef-pages/endpoints.mdx b/fern/products/api-def/ferndef-pages/endpoints.mdx
index ad91ab18f..2fba4152a 100644
--- a/fern/products/api-def/ferndef-pages/endpoints.mdx
+++ b/fern/products/api-def/ferndef-pages/endpoints.mdx
@@ -27,6 +27,10 @@ Each service defines:
To define a service with an empty base path use the empty string: `base-path: ""`
+### Section display name
+
+By default, section names in your API Reference come from service file names (e.g., `user.yml` becomes "User"). To override the display name of a section, [use the `section` property in your `docs.yml`](/docs/api-references/customize-api-reference-layout#renaming-sections).
+
## Endpoints
An endpoint includes:
@@ -41,7 +45,7 @@ An endpoint includes:
- **Successful (200) response** information _(Optional)_
- **Error (non-200) responses** that this endpoint might return _(Optional)_
-## URL path
+### URL path
Each endpoint has a URL path.
@@ -63,7 +67,7 @@ The full path for the endpoint is the concatenation of:
- The service `base-path`
- The endpoint `path`
-## Display name
+### Endpoint display name
The display name will appear as the title of an endpoint. By default, the display name is equal to the 'Title Case' of the endpoint name. If you would like to customize the endpoint name, you can **set the display name**.
@@ -82,7 +86,7 @@ service:
```
-## Path parameters
+### Path parameters
Supply path parameters for your endpoints to create dynamic URLs.
@@ -114,7 +118,7 @@ Services can also have path-parameters:
```
-## Query parameters
+### Query parameters
Each endpoint can specify query parameters:
@@ -135,7 +139,7 @@ service:
```
-### `allow-multiple`
+#### `allow-multiple`
Use `allow-multiple` to specify that a query parameter is allowed
multiple times in the URL, as in `?filter=jane&filter=smith`. This will alter
@@ -152,7 +156,7 @@ parameter.
```
-## Auth
+### Auth
Each endpoint can override the auth behavior specified in the service.
@@ -171,7 +175,7 @@ Each endpoint can override the auth behavior specified in the service.
```
-## Headers
+### Headers
Each endpoint can specify request headers:
@@ -213,7 +217,7 @@ Services can also specify request headers. These headers will cascade to the ser
```
-## Request body
+### Request body
Endpoints can specify a request body type.
@@ -232,7 +236,7 @@ service:
```
-### Inlining a request body
+#### Inlining a request body
If the request body is an object, you can **inline the type declaration**. This
makes the generated SDKs a bit more idiomatic.
@@ -255,7 +259,7 @@ makes the generated SDKs a bit more idiomatic.
```
-## Success response
+### Success response
Endpoints can specify a `response`, which is the type of the body that will be
returned on a successful (200) call.
@@ -279,7 +283,7 @@ types:
```
-## Response status codes
+### Response status codes
You can also use the `status-code` field to specify a custom status code
for a success response.
@@ -306,7 +310,7 @@ types:
```
-## Error responses
+### Error responses
Endpoints can specify error responses, which detail the non-200 responses that
the endpoint might return.
@@ -453,7 +457,7 @@ the request body, path parameters, query parameters, headers, and response body.
```
-### Failed examples
+#### Failed examples
You can also specify examples of failed endpoints calls. Add the `error`
property to a response example to designate which failure you're demonstrating.
@@ -490,7 +494,7 @@ errors:
```
-### Referencing examples from types
+#### Referencing examples from types
To avoid duplication, you can reference examples from types using `$`.
diff --git a/fern/products/api-def/openapi-pages/extensions/overview.md b/fern/products/api-def/openapi-pages/extensions/overview.md
index 4746ffecc..76c1385b1 100644
--- a/fern/products/api-def/openapi-pages/extensions/overview.md
+++ b/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 |
diff --git a/fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx b/fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx
new file mode 100644
index 000000000..1e37a48d6
--- /dev/null
+++ b/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
+```
+
+
+ Alternatively, you can rename sections directly in your [`docs.yml` file](/docs/api-references/customize-api-reference-layout).
+
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 15fa529fc..66897bd88 100644
--- a/fern/products/docs/pages/api-references/customize-api-ref.mdx
+++ b/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
+
+By default, section display names come from [service file names](/api-definition/fern/endpoints#service-definition) (Fern
+Definition) or tag names (OpenAPI) in your spec.
+
+To override the display name of a section, use the `section` property in your `docs.yml` and reference the `lowerCamelCase` version of the original service file name (Fern Definition) or tag name (OpenAPI) in `referenced-packages`.
+
+```yaml title="docs.yml" {4-6}
+navigation:
+ - api: API Reference
+ layout:
+ - section: "Billing" # New section display name
+ referenced-packages:
+ - billing # lowerCamelCase version of original tag/service file name from your spec
+ contents: []
+ - section: "Bank Accounts"
+ referenced-packages:
+ - bankAccounts
+ contents: []
+```
+
+ For OpenAPI, you can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names).
+
+
### Flattening sections
To remove the API Reference title and display the section contents, set `flattened` to `true`.