From 3199aab17542be73f36ed65f9ebdb05ce251b7bf Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 2 Oct 2025 17:00:56 -0400 Subject: [PATCH 1/3] add info about specifying section display names --- fern/products/api-def/api-def.yml | 2 ++ .../openapi-pages/extensions/overview.md | 1 + .../extensions/tag-display-name.mdx | 20 ++++++++++++++++ .../api-references/customize-api-ref.mdx | 24 +++++++++++++++++++ 4 files changed, 47 insertions(+) create mode 100644 fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx 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/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..f2b483c26 --- /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](/api-references/customize-api-reference-layout#renaming-sections). + 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..ba74b7397 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 + +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: [] +``` + + 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) + + + ### Flattening sections To remove the API Reference title and display the section contents, set `flattened` to `true`. From 2e61d95accea0f3fb2dfb72371cb9f52a4ff57a7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 2 Oct 2025 17:08:10 -0400 Subject: [PATCH 2/3] fix link --- .../api-def/openapi-pages/extensions/tag-display-name.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index f2b483c26..1e37a48d6 100644 --- a/fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx +++ b/fern/products/api-def/openapi-pages/extensions/tag-display-name.mdx @@ -16,5 +16,5 @@ tags: ``` - Alternatively, you can rename sections directly in your [`docs.yml` file](/api-references/customize-api-reference-layout#renaming-sections). + Alternatively, you can rename sections directly in your [`docs.yml` file](/docs/api-references/customize-api-reference-layout). From 3467ed7b836400a398136655cde928495dc21aeb Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sat, 4 Oct 2025 14:11:38 -0400 Subject: [PATCH 3/3] clarify info on fern definition section display name --- .../api-def/ferndef-pages/endpoints.mdx | 32 +++++++++++-------- .../api-references/customize-api-ref.mdx | 18 +++++------ 2 files changed, 27 insertions(+), 23 deletions(-) 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/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index ba74b7397..66897bd88 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -98,28 +98,28 @@ To reference an endpoint, you can use either: ### 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`. +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: "User" # New display name + - section: "Billing" # New section display name referenced-packages: - - user-endpoint # Original tag name from your spec + - billing # lowerCamelCase version of original tag/service file name from your spec contents: [] - - section: "Plant" + - section: "Bank Accounts" referenced-packages: - - plant + - bankAccounts contents: [] ``` - 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) + 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`.