diff --git a/fern/products/sdks/guides/configure-global-headers.mdx b/fern/products/sdks/guides/configure-global-headers.mdx
index 53ec1bd15..3d8093d3e 100644
--- a/fern/products/sdks/guides/configure-global-headers.mdx
+++ b/fern/products/sdks/guides/configure-global-headers.mdx
@@ -77,8 +77,11 @@ If you'd like to see this feature, please upvote [this issue](https://github.com
-Use the `x-fern-global-headers` extension to label additional headers as global
-or to alias the names of global headers:
+For OpenAPI specifications, you can configure global headers in two ways:
+
+#### Method 1: OpenAPI Spec Extension
+
+Add global headers directly to your OpenAPI spec using the `x-fern-global-headers` extension to label additional headers as global or to alias the names of global headers:
```yaml title="openapi.yml"
x-fern-global-headers:
@@ -88,14 +91,37 @@ x-fern-global-headers:
optional: true
```
-This configuration yields the following client:
+#### Method 2: `generators.yml` Configuration
+
+Alternatively, you can add headers to the `api` block in your `generators.yml` file:
+
+```yaml title="generators.yml"
+api:
+ - openapi: ./path/to/openapi
+ headers:
+ custom_api_key:
+ name: api_key
+ type: string
+ userpool_id:
+ name: userpool_id
+ type: optional
+```
+
+For more information, see the [`generators.yml` reference documentation](/sdks/reference/generators-yml#headers).
+
+#### Client code
+
+Both of the above configurations produce the same client code:
```python
import os
class Client:
- def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])
+ def __init__(self, *, apiKey: str,
+ userpoolId: typing.Optional[str])
```
+
+
\ No newline at end of file
diff --git a/fern/products/sdks/guides/configure-readme.mdx b/fern/products/sdks/guides/configure-readme.mdx
new file mode 100644
index 000000000..fcbcaf290
--- /dev/null
+++ b/fern/products/sdks/guides/configure-readme.mdx
@@ -0,0 +1,25 @@
+---
+title: Customize README
+description: Guide to configuring the README in your SDK
+---
+
+By default, the README for your SDKs is generated programmatically. You can override this by configuring the `readme` section in `generators.yml` to control the content and structure of generated README files across all your SDKs.
+You can add custom introductions, showcase key endpoints, and organize your SDK documentation with feature sections.
+
+```yaml title="generators.yml"
+readme:
+ introduction: "Welcome to our API"
+ apiReferenceLink: "https://docs.example.com"
+ defaultEndpoint:
+ method: "POST"
+ path: "/users"
+ features:
+ authentication:
+ - method: "POST"
+ path: "/auth/login"
+ users:
+ - method: "GET"
+ path: "/users"
+```
+
+For more detailed information on `readme` configuration, see the [`generators.yml` documentation](/sdks/reference/generators-yml#readme)
\ No newline at end of file
diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx
index 2d1b431ac..ce3b22b7a 100644
--- a/fern/products/sdks/reference/generators-yml-reference.mdx
+++ b/fern/products/sdks/reference/generators-yml-reference.mdx
@@ -64,21 +64,7 @@ Configures authentication methods for your API.
## api
-
Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it.
-
-
-```yaml
-api:
- specs:
- - openapi: "./openapi.yml"
- namespace: "v1"
- settings:
- title-as-schema-name: true
- inline-path-parameters: false
-```
-
-### General Configuration Options
```yaml
api:
@@ -97,19 +83,41 @@ api:
staging: "https://api.staging.com"
```
-
+
List of API specifications or Conjure configuration.
-
+
Authentication configuration for the API.
-
- Default headers to include with API requests.
-
-
-
+
+ Global headers to include with all API requests. You can specify headers as simple string values or as objects with additional configuration for code generation.
+
+ **Simple string values:**
+ ```yaml
+ api:
+ headers:
+ Authorization: "Bearer ${API_TOKEN}"
+ X-App-Version: "1.0.0"
+ ```
+
+ **Advanced configuration with type information:**
+ ```yaml
+ api:
+ - openapi: ./path/to/openapi
+ headers:
+ X-Version:
+ # The variable name to use in generated SDK code.
+ # If not specified, uses the header name.
+ name: version
+ # The type of the header value for code generation
+ # (e.g., "string", "literal<'value'>", "number").
+ type: literal<"1234">
+ ```
+
+
+
Environment configurations for different deployment targets.
@@ -135,87 +143,87 @@ api:
max-depth: 2
```
-
+
Path to the OpenAPI specification file.
-
+
URL of the API definition origin for polling updates.
-
+
Path to OpenAPI overrides file.
-
+
Namespace for the specification.
-
+
OpenAPI-specific generation settings.
-
+
Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.
-
+
Whether to include path parameters within the generated in-lined request.
-
+
Whether to prefer undiscriminated unions with literals.
-
+
Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).
-
+
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
-
+
Enables parsing deep object query parameters.
-
+
Enables exploring readonly schemas in OpenAPI specifications.
-
+
Enables respecting forward compatible enums in OpenAPI specifications.
-
+
Enables using the `bytes` type for binary responses. Defaults to file stream.
-
+
The default encoding of form parameters. Options: `form`, `json`.
-
+
Configure what `additionalProperties` should default to when not explicitly defined on a schema.
-
+
If true, convert strings with format date to strings. If false, convert to dates.
-
+
If true, preserve oneOf structures with a single schema. If false, unwrap them.
-
+
Endpoints to include in the generated SDK (e.g., "POST /users").
-
+
Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.
-
+
Controls the maximum depth for which optional properties will have examples generated in responses.
@@ -234,35 +242,35 @@ api:
respect-nullable-schemas: true
```
-
+
Path to the AsyncAPI specification file.
-
+
URL of the API definition origin for polling updates.
-
+
Path to AsyncAPI overrides file.
-
+
Namespace for the specification.
-
+
AsyncAPI-specific generation settings.
-
+
What version of message naming to use for AsyncAPI messages. Options: `v1`, `v2`.
-
+
Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern.
-
+
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
@@ -277,37 +285,37 @@ api:
local-generation: true
```
-
+
Protocol Buffers configuration.
-
+
Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`).
-
+
Path to the `.proto` directory root (e.g., `proto`).
-
+
Path to the overrides configuration.
-
+
Whether to compile `.proto` files locally. Defaults to remote generation.
#### OpenRPC
-
+
Path to the OpenRPC specification file.
-
+
Path to OpenRPC overrides file.
-
+
Namespace for the specification.
@@ -319,7 +327,7 @@ api:
conjure: "./conjure-api.yml"
```
-
+
Path to Conjure specification file.
diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml
index c771d7522..a6a54a5d6 100644
--- a/fern/products/sdks/sdks.yml
+++ b/fern/products/sdks/sdks.yml
@@ -202,6 +202,9 @@ navigation:
- page: Filter Your Endpoints (Audiences)
path: ./guides/filter-your-endpoints-audiences.mdx
slug: audiences
+ - page: Customize the README for your SDKs
+ path: ./guides/configure-readme.mdx
+ slug: readme
- page: Self-host Fern's SDK Generators
hidden: true
path: ./guides/self-host-fern-generators.mdx