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

Author: devalog

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/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: ""`
 </Info>
 
+### 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:
 ```
 </CodeBlock>
 
-## Path parameters
+### Path parameters
 
 Supply path parameters for your endpoints to create dynamic URLs.
 
@@ -114,7 +118,7 @@ Services can also have path-parameters:
   ```
 </CodeBlock>
 
-## Query parameters
+### Query parameters
 
 Each endpoint can specify query parameters:
 
@@ -135,7 +139,7 @@ service:
 ```
 </CodeBlock>
 
-### `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.
 ```
 </CodeBlock>
 
-## 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.
   ```
 </CodeBlock>
 
-## 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
   ```
 </CodeBlock>
 
-## Request body
+### Request body
 
 Endpoints can specify a request body type.
 
@@ -232,7 +236,7 @@ service:
 ```
 </CodeBlock>
 
-### 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.
   ```
 </CodeBlock>
 
-## 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:
 ```
 </CodeBlock>
 
-## 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:
 ```
 </CodeBlock>
 
-## 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.
   ```
 </CodeBlock>
 
-### 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:
 ```
 </CodeBlock>
 
-### Referencing examples from types
+#### Referencing examples from types
 
 To avoid duplication, you can reference examples from types using `$`.
 

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
+
+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: []
+```
+<Note>
+  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). 
+</Note>
+
 ### Flattening sections
 To remove the API Reference title and display the section contents, set `flattened` to `true`.