Merge branch 'main' into ask-fern-rbac-docs

Author: devalog

fern/assets/styles.css

@@ -63,3 +63,24 @@ You can inline the schema of the payload by doing the following:
   ```
 </CodeBlock>
 
+## Generate webhook reference
+
+Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. 
+
+Your webhook reference can be a single documentation page:
+
+```yml docs.yml
+navigation:
+  - api: Webhook Reference # Display name for this page
+    api-name: webhooks-v1 # Directory containing webhook definition
+```
+
+Or you can configure individual documentation pages per webhook event:
+
+```yaml title="docs.yml"
+navigation:
+  - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}
+```
+
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference).
+

fern/footer-dist/output.js

@@ -164,6 +164,10 @@ components:
         prefix: "Token " # Optional      
 ```
 
+<Info> 
+  The `prefix` option lets you automatically add a prefix to API keys. This is useful when your API expects tokens in a specific format like `"Bearer abc123"` or `"Token abc123"`.
+</Info>
+
 The generated SDK would look like: 
 
 ```ts index.ts

fern/products/api-def/ferndef-pages/webhooks.mdx

@@ -14,11 +14,14 @@ The table below shows all available extensions and links to detailed documentati
 | --- | --- |
 | [`x-fern-version`](./api-version) | Configure API version schemes and headers |
 | [`x-fern-audiences`](./audiences) | Filter endpoints, schemas, and properties by audience |
+| [`x-fern-basic`](/api-definitions/openapi/authentication#basic-security-scheme) | Customize basic authentication parameter names and environment variables |
+| [`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-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 |
+| [`x-fern-header`](/api-definitions/openapi/authentication#apikey-security-scheme) | Customize API key header authentication parameter names and environment variables |
 | [`x-fern-ignore`](./ignoring-elements) | Skip reading specific endpoints or schemas |
 | [`x-fern-sdk-method-name`](./method-names) | Customize SDK method names |
 | [`x-fern-sdk-group-name`](./method-names) | Organize methods into SDK groups |

fern/products/api-def/openapi-pages/auth.mdx

@@ -3,13 +3,13 @@ title: What is an OpenAPI Specification?
 description: OpenAPI is a standard for documenting REST APIs
 ---
 
-The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification 
+The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification is
 written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes. 
 Fern is compatible with the latest OAS release, which is currently [v3.1.1](https://spec.openapis.org/#openapi-specification).
 
 Below is an example of an OpenAPI file: 
 
-```yaml openapi.yml 
+```yaml title="openapi.yml" maxLines=10
 openapi: 3.0.2
 info:
   title: Petstore - OpenAPI 3.0
@@ -101,8 +101,46 @@ components:
       name: api_key
       in: header
 ```
+## Best practices
 
-## Setup your fern folder
+Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation:
+
+- **Organize with proper project structure.** Follow the instructions at [Project structure](/api-definitions/overview/project-structure) to clearly organize the directories that contain your definition and other related files. 
+- **Add `operationId` to endpoints.** Include a clear `operationId` for each endpoint to control the function names generated in your SDKs. (Or use [extensions to customize group and method names](/api-definitions/openapi/extensions/method-names).)
+- **Reference schemas instead of inlining.** Define reusable schemas in the `components/schemas` section and reference them with `$ref`. This promotes consistency, reduces duplication, and makes maintenance easier.
+  <Accordion title="Example of referencing schemas">
+    ```yaml title="openapi.yml" {8, 14, 17-25}
+    paths:
+      /pets:
+        post:
+          requestBody:
+            content:
+              application/json:
+                schema:
+                  $ref: '#/components/schemas/Pet'  # Clean reference
+          responses:
+            '200':
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/Pet'  # Reused easily
+    components:
+      schemas:
+        Pet:                        # Defined once, used everywhere
+          type: object
+          properties:
+            name:
+              type: string
+            status:
+              type: string
+              enum: [available, pending, sold]
+    ```
+  </Accordion>
+- **Use overrides and Fern extensions for customization.** Customize your specification using Fern [extensions](/api-definitions/openapi/extensions/overview) housed in an [overrides file](/api-definitions/overview/overrides). This lets you modify generation behavior without changing your core OpenAPI definition.  
+
+Once your OpenAPI spec follows these practices, you're ready to set up your fern folder. 
+
+## Set up your fern folder
 
 <Info> Considering options to generate an OpenAPI spec? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) </Info>
 

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

@@ -8,15 +8,10 @@ Fern supports two methods for defining webhooks in your OpenAPI specification:
 1. Using OpenAPI 3.1's native webhook support (recommended)
 2. Using Fern's `x-fern-webhook` extension
 
-## OpenAPI 3.1 Webhooks
+## OpenAPI 3.1 webhooks
 
 For OpenAPI 3.1 specifications, use the `webhooks` top-level field to define your webhook operations. Each webhook requires an `operationId` to be properly processed by Fern.
 
-To create dedicated pages in your API reference documentation for each webhook
-event, include `tags` and complete `example` data in your schema. Then, [add a
-reference in your
-`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi).
-
 ```yaml openapi.yml {4, 7-8, 42-48}
 webhooks:
   newPlant:
@@ -71,15 +66,10 @@ webhooks:
           description: Return a 200 status to indicate that the data was received successfully
 ```
 
-## Fern Webhook Extension
+## Fern webhook extension
 
 For OpenAPI 3.0, use the `x-fern-webhook: true` extension to define webhooks. Fern will treat the `requestBody` as the webhook payload.
 
-To create dedicated pages in your API reference documentation for each webhook
-event, include `tags` and complete `example` data in your schema. Then, [add a
-reference in your
-`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi).
-
 ```yaml openapi.yml {6-8, 23-25}
 paths: 
   /payment/updated/: 
@@ -112,3 +102,24 @@ paths:
 The path that you choose when defining a webhook can be arbitrary. Since webhooks 
 can be sent to any server, Fern just ignores the path.
 </Info>
+
+## Generate webhook reference
+
+Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. 
+
+Your webhook reference can be a single documentation page:
+
+```yml docs.yml
+navigation:
+  - api: Webhook Reference # Display name for this page
+    api-name: webhooks-v1 # Name of webhook definition directory
+```
+
+Or you can configure individual documentation pages per webhook event:
+
+```yaml title="docs.yml"
+navigation:
+  - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name}
+```
+
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference).

fern/products/api-def/openapi-pages/overview.mdx

@@ -21,13 +21,13 @@ The interface maintains your site's design language while providing a familiar c
 
 The main parts of the Ask Fern system are:
 
-* **Content indexing** – Fern automatically processes your documentation pages,
-  breaking them into semantic chunks and converting each chunk into a vector
-  using sentence embedding models. They're stored in a database that serves as
-  Ask Fern's search index. 
+* **Content and code indexing** – Fern automatically processes your
+  documentation pages and Fern-generated SDK code, breaking them into semantic
+  chunks and converting each chunk into a vector using sentence embedding
+  models. They're stored in a database that serves as Ask Fern's search index. 
 * **Query processing** – When users ask questions, Ask Fern vectorizes their
-  query and searches the database to find the most relevant documentation
-  chunks. If you have [role-based access control](/docs/authentication/rbac) configured, Ask Fern filters results based on the user's permissions.
+  query and searches the database to find the most relevant documentation and
+  code chunks. If you have [role-based access control](/docs/authentication/rbac) configured, Ask Fern filters results based on the user's permissions.
 * **Response generation** – Ask Fern uses the retrieved chunks as context to
   generate accurate answers with [citations](/ask-fern/features/citations) for the user. If the initial context isn't sufficient, it performs an additional keyword search. 
 

fern/products/api-def/openapi-pages/webhooks.mdx

@@ -40,7 +40,7 @@ Ask Fern helps you:
 
   <Card 
     title="Citations" 
-    icon="regular quote-right"
+    icon="fa-solid fa-quote-right"
     href="/learn/ask-fern/features/citations" 
     >
     Point users to the exact source of the answer. 

fern/products/ask-fern/pages/getting-started/how-it-works.mdx

@@ -5,7 +5,7 @@
 **`(feat):`** Auto generate examples for HTTP endpoint error responses.
 
 ## 0.69.2
-**`(fix):`** Add custom license name extraction for Java SDK generation. The CLI now reads the first line 
+**`(fix):`** Add custom license name extraction for Java SDK generation. The CLI now reads the first line
 from custom LICENSE files and passes it to generators via the _fernLicenseName field in customConfig.