From 7f730e1bd36546f7888d17455ebbeefc282dd341 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Thu, 21 May 2026 15:44:54 +0000
Subject: [PATCH 1/3] Standardize OpenAPI spec file references from .yml to
.yaml
---
fern/products/cli-api-reference/pages/commands.mdx | 2 +-
.../products/docs/pages/api-references/generate-api-ref.mdx | 6 +++---
.../docs/pages/api-references/generate-webhook-ref.mdx | 6 +++---
fern/products/docs/pages/getting-started/quickstart.mdx | 2 +-
fern/snippets/openapi-specs.mdx | 2 +-
5 files changed, 9 insertions(+), 9 deletions(-)
diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx
index cb5aad6cc7..2be0205bc7 100644
--- a/fern/products/cli-api-reference/pages/commands.mdx
+++ b/fern/products/cli-api-reference/pages/commands.mdx
@@ -73,7 +73,7 @@ hideOnThisPage: true
```bash
# Initialize from local file
- fern init --openapi ./path/to/openapi.yml
+ fern init --openapi ./path/to/openapi.yaml
# Initialize from URL
fern init --openapi https://link.buildwithfern.com/petstore-openapi
diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx
index 387ca45b10..44ce154d5a 100644
--- a/fern/products/docs/pages/api-references/generate-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx
@@ -20,7 +20,7 @@ Add your specification file to your `/fern` directory and create a `generators.y
```yaml generators.yml
api:
specs:
- - openapi: "./openapi.yml"
+ - openapi: "./openapi.yaml"
```
@@ -52,11 +52,11 @@ To include multiple, distinct API definitions in your documentation, use the `ap
-
+
-
+
diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
index 5f42d459e0..926f96690b 100644
--- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
+++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
@@ -19,7 +19,7 @@ Add your specification file to your `/fern` directory and create a `generators.y
```yaml generators.yml
api:
- path: openapi/openapi.yml
+ path: openapi/openapi.yaml
```
@@ -55,13 +55,13 @@ To include multiple webhook definitions in your documentation, use the `api-name
-
+
-
+
diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx
index fbaea6a04e..03aa41336e 100644
--- a/fern/products/docs/pages/getting-started/quickstart.mdx
+++ b/fern/products/docs/pages/getting-started/quickstart.mdx
@@ -185,7 +185,7 @@ This guide covers the CLI path. A browser-based guided setup also exists at http
If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec:
```bash
- fern init --openapi /path/to/openapi.yml
+ fern init --openapi /path/to/openapi.yaml
```
Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref):
diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx
index a40a28a2a2..1abde5160d 100644
--- a/fern/snippets/openapi-specs.mdx
+++ b/fern/snippets/openapi-specs.mdx
@@ -1,7 +1,7 @@
```yaml title="generators.yml"
api:
specs:
- - openapi: "./openapi.yml"
+ - openapi: "./openapi.yaml"
origin: "https://api.example.com/openapi.json"
overlays: "./openapi-overlays.yml"
overrides: "./openapi-overrides.yml" # or a list of paths
From b1a5019f26c879b7c48862de4d0a8a422285e84a Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Thu, 21 May 2026 15:54:20 +0000
Subject: [PATCH 2/3] Standardize OpenAPI spec references to .yml and add note
that both extensions work
---
.../api-def/openapi/extensions/api-version.mdx | 2 +-
.../api-def/openapi/extensions/method-names.mdx | 6 +++---
fern/products/cli-api-reference/pages/commands.mdx | 2 +-
fern/products/cli-generator/openapi-extensions.mdx | 14 +++++++-------
.../docs/pages/api-references/generate-api-ref.mdx | 6 +++---
.../pages/api-references/generate-webhook-ref.mdx | 6 +++---
.../pages/getting-started/project-structure.mdx | 8 ++++----
.../docs/pages/getting-started/quickstart.mdx | 6 +++---
.../sdks/deep-dives/customize-method-names.mdx | 2 +-
fern/snippets/open-api-method-names.mdx | 6 +++---
fern/snippets/openapi-specs.mdx | 2 +-
11 files changed, 30 insertions(+), 30 deletions(-)
diff --git a/fern/products/api-def/openapi/extensions/api-version.mdx b/fern/products/api-def/openapi/extensions/api-version.mdx
index b5935912e8..6fb72e64d7 100644
--- a/fern/products/api-def/openapi/extensions/api-version.mdx
+++ b/fern/products/api-def/openapi/extensions/api-version.mdx
@@ -7,7 +7,7 @@ description: Configure API version schemes and headers using `x-fern-version` ex
You can define your API version scheme, such as a `X-API-Version` header. The supported versions and default value are specified like so:
-```yaml title="openapi.yaml"
+```yaml title="openapi.yml"
x-fern-version:
header: X-API-Version
default: "2.0.0"
diff --git a/fern/products/api-def/openapi/extensions/method-names.mdx b/fern/products/api-def/openapi/extensions/method-names.mdx
index 82c460faef..1b61e7d791 100644
--- a/fern/products/api-def/openapi/extensions/method-names.mdx
+++ b/fern/products/api-def/openapi/extensions/method-names.mdx
@@ -14,7 +14,7 @@ Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to contr
In the example below, Fern will generate a
method called `client.users.create()` for the `POST /users` endpoint.
-```yaml title="openapi.yaml" {4-5}
+```yaml title="openapi.yml" {4-5}
paths:
/users:
post:
@@ -28,7 +28,7 @@ If you omit the `x-fern-sdk-group-name` extension, the generated SDK method
will live at the root of the client rather than nested under a resource group.
In the example below, Fern will generate a method called `client.send()`:
-```yaml title="openapi.yaml" {4}
+```yaml title="openapi.yml" {4}
paths:
/send:
post:
@@ -46,7 +46,7 @@ The generated SDK method preserves the order of group names.
In the example below, Fern will generate a method called `client.users.notifications.send()`:
-```yaml title="openapi.yaml"
+```yaml title="openapi.yml"
paths:
/users/notifications:
post:
diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx
index 2be0205bc7..cb5aad6cc7 100644
--- a/fern/products/cli-api-reference/pages/commands.mdx
+++ b/fern/products/cli-api-reference/pages/commands.mdx
@@ -73,7 +73,7 @@ hideOnThisPage: true
```bash
# Initialize from local file
- fern init --openapi ./path/to/openapi.yaml
+ fern init --openapi ./path/to/openapi.yml
# Initialize from URL
fern init --openapi https://link.buildwithfern.com/petstore-openapi
diff --git a/fern/products/cli-generator/openapi-extensions.mdx b/fern/products/cli-generator/openapi-extensions.mdx
index 01b516cc4f..cbd9ed74d9 100644
--- a/fern/products/cli-generator/openapi-extensions.mdx
+++ b/fern/products/cli-generator/openapi-extensions.mdx
@@ -16,7 +16,7 @@ The CLI generator reads several [Fern OpenAPI extensions](/learn/api-definitions
Determines the subcommand group hierarchy. Each list element becomes a nested subcommand, with names converted from camelCase to kebab-case.
-```yaml title="openapi.yaml" {4-6}
+```yaml title="openapi.yml" {4-6}
paths:
/scheduled-events/{uuid}/invitees:
get:
@@ -32,7 +32,7 @@ Produces: `cli scheduled-events invitees list-event-invitees`
Sets the leaf command name (used as-is).
-```yaml title="openapi.yaml" {4}
+```yaml title="openapi.yml" {4}
paths:
/users/me:
get:
@@ -53,7 +53,7 @@ See [SDK method names](/learn/api-definitions/openapi/extensions/method-names) f
Excludes operations or parameters from the generated CLI. An ignored operation produces no command; an ignored parameter produces no flag.
-```yaml title="openapi.yaml" {4}
+```yaml title="openapi.yml" {4}
paths:
/internal/debug:
get:
@@ -62,7 +62,7 @@ paths:
At the parameter level:
-```yaml title="openapi.yaml" {7}
+```yaml title="openapi.yml" {7}
paths:
/users:
get:
@@ -91,7 +91,7 @@ Adds a status badge next to the command in `--help` output.
| `deprecated` | `[Deprecated]` |
| `legacy` | `[Legacy]` |
-```yaml title="openapi.yaml" {4}
+```yaml title="openapi.yml" {4}
paths:
/v2/reports:
get:
@@ -108,7 +108,7 @@ See [Availability](/learn/api-definitions/openapi/extensions/availability) for m
Overrides the CLI flag name derived from a parameter. By default, parameter names are converted to kebab-case for use as flags.
-```yaml title="openapi.yaml" {9}
+```yaml title="openapi.yml" {9}
paths:
/users:
get:
@@ -130,7 +130,7 @@ See [Customize parameter names](/learn/api-definitions/openapi/extensions/parame
Enables auto-pagination for an endpoint. When present, the CLI recognizes `--page-all`, `--page-limit`, and `--page-delay` flags for that command.
-```yaml title="openapi.yaml" {5-8}
+```yaml title="openapi.yml" {5-8}
paths:
/plants:
get:
diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx
index 44ce154d5a..387ca45b10 100644
--- a/fern/products/docs/pages/api-references/generate-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx
@@ -20,7 +20,7 @@ Add your specification file to your `/fern` directory and create a `generators.y
```yaml generators.yml
api:
specs:
- - openapi: "./openapi.yaml"
+ - openapi: "./openapi.yml"
```
@@ -52,11 +52,11 @@ To include multiple, distinct API definitions in your documentation, use the `ap
-
+
-
+
diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
index 926f96690b..5f42d459e0 100644
--- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
+++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx
@@ -19,7 +19,7 @@ Add your specification file to your `/fern` directory and create a `generators.y
```yaml generators.yml
api:
- path: openapi/openapi.yaml
+ path: openapi/openapi.yml
```
@@ -55,13 +55,13 @@ To include multiple webhook definitions in your documentation, use the `api-name
-
+
-
+
diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx
index 7373c817e6..15db917d8f 100644
--- a/fern/products/docs/pages/getting-started/project-structure.mdx
+++ b/fern/products/docs/pages/getting-started/project-structure.mdx
@@ -19,7 +19,7 @@ The configuration files for your docs live in the `fern` folder:
-
+
@@ -132,7 +132,7 @@ To generate [API Reference](/docs/api-references/generate-api-ref) documentation
```yaml title="generators.yml"
api:
specs:
- - openapi: openapi.yaml
+ - openapi: openapi.yml
```
You can optionally [add an overlays file](/learn/api-definitions/openapi/overlays) for additional customizations. To see this in practice, check out [Fluidstack's Fern configuration](https://github.com/fluidstackio/fern-config/tree/main/fern/openapi).
@@ -144,7 +144,7 @@ To generate [API Reference](/docs/api-references/generate-api-ref) documentation
```yaml title="generators.yml"
api:
specs:
- - openapi: openapi.yaml
+ - openapi: openapi.yml
- asyncapi: asyncapi.yaml
```
@@ -162,7 +162,7 @@ To generate [API Reference](/docs/api-references/generate-api-ref) documentation
-
+
diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx
index 03aa41336e..d41036be88 100644
--- a/fern/products/docs/pages/getting-started/quickstart.mdx
+++ b/fern/products/docs/pages/getting-started/quickstart.mdx
@@ -88,7 +88,7 @@ This guide covers the CLI path. A browser-based guided setup also exists at http
-
+
@@ -182,10 +182,10 @@ This guide covers the CLI path. A browser-based guided setup also exists at http
- If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec:
+ If you cloned the starter template, you already have an `openapi.yml` file with sample API definitions (both `.yml` and `.yaml` work interchangeably). If you started from scratch, add your OpenAPI spec:
```bash
- fern init --openapi /path/to/openapi.yaml
+ fern init --openapi /path/to/openapi.yml
```
Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref):
diff --git a/fern/products/sdks/deep-dives/customize-method-names.mdx b/fern/products/sdks/deep-dives/customize-method-names.mdx
index cf8c6c38e5..7384afd46e 100644
--- a/fern/products/sdks/deep-dives/customize-method-names.mdx
+++ b/fern/products/sdks/deep-dives/customize-method-names.mdx
@@ -41,7 +41,7 @@ Fern generates SDK methods using your configured group and method names. Casing
Configure how endpoints map to SDK method and group names in your API definition:
-```yaml title="openapi.yaml" {4-5}
+```yaml title="openapi.yml" {4-5}
paths:
/users:
post:
diff --git a/fern/snippets/open-api-method-names.mdx b/fern/snippets/open-api-method-names.mdx
index 8aebe99b7c..9544041997 100644
--- a/fern/snippets/open-api-method-names.mdx
+++ b/fern/snippets/open-api-method-names.mdx
@@ -7,7 +7,7 @@ Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to contr
In the example below, Fern will generate a
method called `client.users.create()` for the `POST /users` endpoint.
-```yaml title="openapi.yaml" {4-5}
+```yaml title="openapi.yml" {4-5}
paths:
/users:
post:
@@ -21,7 +21,7 @@ If you omit the `x-fern-sdk-group-name` extension, the generated SDK method
will live at the root of the client rather than nested under a resource group.
In the example below, Fern will generate a method called `client.send()`:
-```yaml title="openapi.yaml" {4}
+```yaml title="openapi.yml" {4}
paths:
/send:
post:
@@ -39,7 +39,7 @@ The generated SDK method preserves the order of group names.
In the example below, Fern will generate a method called `client.users.notifications.send()`:
-```yaml title="openapi.yaml"
+```yaml title="openapi.yml"
paths:
/users/notifications:
post:
diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx
index 1abde5160d..a40a28a2a2 100644
--- a/fern/snippets/openapi-specs.mdx
+++ b/fern/snippets/openapi-specs.mdx
@@ -1,7 +1,7 @@
```yaml title="generators.yml"
api:
specs:
- - openapi: "./openapi.yaml"
+ - openapi: "./openapi.yml"
origin: "https://api.example.com/openapi.json"
overlays: "./openapi-overlays.yml"
overrides: "./openapi-overrides.yml" # or a list of paths
From 9c24116c81c6c9a9982e35562b4a5f08c1bf63a3 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Thu, 21 May 2026 16:00:24 +0000
Subject: [PATCH 3/3] Add note about .yml/.yaml interchangeability to project
structure page
---
.../products/docs/pages/getting-started/project-structure.mdx | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx
index 15db917d8f..f8cb10f3a3 100644
--- a/fern/products/docs/pages/getting-started/project-structure.mdx
+++ b/fern/products/docs/pages/getting-started/project-structure.mdx
@@ -61,6 +61,10 @@ The `assets` folder contains any images or videos used in your documentation. Yo
The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings. Only files referenced in your `docs.yml` navigation (or discovered via a [`folder` configuration](/learn/docs/configuration/navigation#auto-populate-from-folder)) are included in builds — any unreferenced files are ignored.
+
+Fern treats `.yml` and `.yaml` extensions identically. This applies to all YAML files in a Fern project, including `docs.yml`, `generators.yml`, and API specification files.
+
+
For complete configuration options, see the [`docs.yml` reference](/docs/configuration/site-level-settings).