add overlay/embed info to asyncapi and openrpc

Author: devalog

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

@@ -48,7 +48,7 @@ navigation:
             path: ./openapi-pages/extensions/examples.mdx
           - page: Global headers
             path: ./openapi-pages/extensions/global-headers.mdx
-          - page: Ignoring schemas or endpoints
+          - page: Ignoring elements
             path: ./openapi-pages/extensions/ignore.mdx
           - page: SDK method names
             path: ./openapi-pages/extensions/method-names.mdx
@@ -109,7 +109,7 @@ navigation:
             path: ./asyncapi-pages/extensions/error-handling.mdx
           - page: Request + response examples
             path: ./asyncapi-pages/extensions/examples.mdx
-          - page: Ignoring operations, channels, or schemas
+          - page: Ignoring elements
             path: ./asyncapi-pages/extensions/ignore.mdx
           - page: SDK method names
             path: ./asyncapi-pages/extensions/method-names.mdx
@@ -168,7 +168,7 @@ navigation:
             path: ./openrpc-pages/extensions/error-handling.mdx
           - page: Request + response examples
             path: ./openrpc-pages/extensions/examples.mdx
-          - page: Ignoring methods or schemas
+          - page: Ignoring elements
             path: ./openrpc-pages/extensions/ignore.mdx
           - page: SDK method names
             path: ./openrpc-pages/extensions/method-names.mdx
@@ -231,7 +231,7 @@ navigation:
             path: ./grpc-pages/extensions/error-handling.mdx
           - page: Request + response examples
             path: ./grpc-pages/extensions/examples.mdx
-          - page: Ignoring services, methods, or messages
+          - page: Ignoring elements
             path: ./grpc-pages/extensions/ignore.mdx
           - page: SDK method names
             path: ./grpc-pages/extensions/method-names.mdx

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

@@ -3,7 +3,7 @@ title: Overview of AsyncAPI extensions
 description: Learn about Fern's AsyncAPI extensions for generating higher-quality SDKs
 ---
 
-Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs.
+Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your AsyncAPI specification.
 
 ## Available extensions
 
@@ -22,4 +22,6 @@ The table below shows all available extensions and links to detailed documentati
 
 <Note title="Request a new extension">
     If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
-</Note>
+</Note>
+
+<Markdown src="/snippets/overlay-embed-extensions.mdx" />

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

@@ -29,72 +29,7 @@ The table below shows all available extensions and links to detailed documentati
     If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
 </Note>
 
-## Overlaying extensions
-
-Overlaying extensions allows you to keep your original OpenAPI specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your OpenAPI spec, or when you want to maintain a pristine source specification.
-
-To use overlays, specify an overrides file in your `generators.yml` configuration.
-
-The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original OpenAPI specification.
-
-<CodeBlocks>
-    ```yaml title="generators.yml" {3}
-    api:
-      path: ./openapi/openapi.yaml
-      overrides: ./openapi/overrides.yaml
-    default-group: sdk
-    groups:
-      sdk:
-        generators:
-          - name: fernapi/fern-python-sdk
-            version: 2.2.0
-    ```
-
-    ```yaml title="overrides.yml" {4-5}
-    paths:
-      /users:
-        get:
-          x-fern-sdk-group-name: users
-          x-fern-sdk-method-name: get
-    ```
-
-    ```yaml title="Overlaid OpenAPI" {4-5}
-    paths:
-      /users:
-        get:
-          x-fern-sdk-group-name: users
-          x-fern-sdk-method-name: get
-          summary: Get a list of users
-          description: Retrieve a list of users from the system.
-          responses:
-            '200':
-              description: Successful response
-            '500':
-              description: Internal Server Error
-    ```
-
-</CodeBlocks>
-
-## Embedding extensions
-
-Instead of using overlay files, you can embed Fern extensions directly within your OpenAPI specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions.
-
-### Direct embedding in OpenAPI
-
-You can add Fern extensions directly to your OpenAPI specification:
-
-```yaml title="openapi.yml"
-paths:
-  /users:
-    get:
-      x-fern-sdk-group-name: users
-      x-fern-sdk-method-name: listUsers
-      x-fern-availability: generally-available
-      summary: Get a list of users
-      responses:
-        '200':
-          description: Successful response
-```
+<Markdown src="/snippets/overlay-embed-extensions.mdx" />
 
 ### FastAPI
 

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

@@ -3,12 +3,12 @@ title: Overview of OpenRPC extensions
 description: Learn about Fern's OpenRPC extensions for generating higher-quality SDKs
 ---
 
-Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs.
-
-The table below shows all available extensions and links to detailed documentation for each one.
+Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenRPC specification.
 
 ## Available extensions
 
+The table below shows all available extensions and links to detailed documentation for each one.
+
 | Extension | Description |
 | --- | --- |
 | [`x-fern-ignore`](./ignore) | Skip reading specific methods or schemas |
@@ -25,4 +25,6 @@ The table below shows all available extensions and links to detailed documentati
 
 <Note title="Request a new extension">
     If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.
-</Note>
+</Note>
+
+<Markdown src="/snippets/overlay-embed-extensions.mdx" />

fern/snippets/overlay-embed-extensions.mdx

@@ -0,0 +1,66 @@
+## Overlaying extensions
+
+Overlaying extensions allows you to keep your original API specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your API spec, or when you want to maintain a pristine source specification.
+
+To use overlays, specify an overrides file in your `generators.yml` configuration.
+
+The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original API specification.
+
+<CodeBlocks>
+    ```yaml title="generators.yml" {3}
+    api:
+      path: ./spec-folder/spec-file.yaml
+      overrides: ./spec-folder/overrides.yaml # Reference your overrides file
+    default-group: sdk
+    groups:
+      sdk:
+        generators:
+          - name: fernapi/fern-python-sdk
+            version: 2.2.0
+    ```
+
+    ```yaml title="overrides.yml" {4-5}
+    paths:
+      /users:
+        get:
+          x-fern-sdk-group-name: users
+          x-fern-sdk-method-name: get
+    ```
+
+    ```yaml title="Overlaid spec" {4-5}
+    paths:
+      /users:
+        get:
+          x-fern-sdk-group-name: users
+          x-fern-sdk-method-name: get
+          summary: Get a list of users
+          description: Retrieve a list of users from the system.
+          responses:
+            '200':
+              description: Successful response
+            '500':
+              description: Internal Server Error
+    ```
+
+</CodeBlocks>
+
+## Embedding extensions
+
+Instead of using overlay files, you can embed Fern extensions directly within your API specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions.
+
+### Direct embedding
+
+You can add Fern extensions directly to your API specification:
+
+```yaml title="spec-file.yml" {4-6}
+paths:
+  /users:
+    get:
+      x-fern-sdk-group-name: users
+      x-fern-sdk-method-name: listUsers
+      x-fern-availability: generally-available
+      summary: Get a list of users
+      responses:
+        '200':
+          description: Successful response
+```