Skip to content

Expand docs on global headers, add readme deep dive #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 2, 2025
+125 −63
Merged

Expand docs on global headers, add readme deep dive #325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
56d5ca4
update info on global headers
devalog Aug 2, 2025
07a4588
add new readme guide
devalog Aug 2, 2025
47dbc1b
update global headers example code
devalog Aug 2, 2025
d1825b3
formatting fixes
devalog Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 30 additions & 4 deletions fern/products/sdks/guides/configure-global-headers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,11 @@ If you'd like to see this feature, please upvote [this issue](https://github.com
</Accordion>
<Accordion title="OpenAPI">

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:
Expand All @@ -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<string>
```

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])
```


</Accordion>
</AccordionGroup>
25 changes: 25 additions & 0 deletions fern/products/sdks/guides/configure-readme.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
126 changes: 67 additions & 59 deletions fern/products/sdks/reference/generators-yml-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,21 +64,7 @@ Configures authentication methods for your API.

## api

<ParamField path="api" type="APIConfigurationSchema" toc={true}>
Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it.
</ParamField>

```yaml
api:
specs:
- openapi: "./openapi.yml"
namespace: "v1"
settings:
title-as-schema-name: true
inline-path-parameters: false
```

### General Configuration Options

```yaml
api:
Expand All @@ -97,19 +83,41 @@ api:
staging: "https://api.staging.com"
```

<ParamField path="api.specs" type="list<SpecSchema> | ConjureSchema" required={true} toc={true}>
<ParamField path="specs" type="list<SpecSchema> | ConjureSchema" required={true} toc={true}>
List of API specifications or Conjure configuration.
</ParamField>

<ParamField path="api.auth" type="ApiAuthSchema" toc={true}>
<ParamField path="auth" type="ApiAuthSchema" toc={true}>
Authentication configuration for the API.
</ParamField>

<ParamField path="api.headers" type="map<string, string>" toc={true}>
Default headers to include with API requests.
</ParamField>

<ParamField path="api.environments" type="EnvironmentsSchema" toc={true}>
<ParamField path="headers" type="map<string, HeaderValue>" toc={true}>
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">
```
</ParamField>

<ParamField path="environments" type="EnvironmentsSchema" toc={true}>
Environment configurations for different deployment targets.
</ParamField>

Expand All @@ -135,87 +143,87 @@ api:
max-depth: 2
```

<ParamField path="specs[].openapi" type="string" required={true} toc={true}>
<ParamField path="openapi" type="string" required={true} toc={true}>
Path to the OpenAPI specification file.
</ParamField>

<ParamField path="specs[].origin" type="string" toc={true}>
<ParamField path="origin" type="string" toc={true}>
URL of the API definition origin for polling updates.
</ParamField>

<ParamField path="specs[].overrides" type="string" toc={true}>
<ParamField path="overrides" type="string" toc={true}>
Path to OpenAPI overrides file.
</ParamField>

<ParamField path="specs[].namespace" type="string" toc={true}>
<ParamField path="namespace" type="string" toc={true}>
Namespace for the specification.
</ParamField>

<ParamField path="specs[].settings" type="OpenAPISettingsSchema" toc={true}>
<ParamField path="settings" type="OpenAPISettingsSchema" toc={true}>
OpenAPI-specific generation settings.
</ParamField>

<ParamField path="settings.title-as-schema-name" type="boolean" default="true" toc={true}>
<ParamField path="title-as-schema-name" type="boolean" default="true" toc={true}>
Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.
</ParamField>

<ParamField path="settings.inline-path-parameters" type="boolean" default="false" toc={true}>
<ParamField path="inline-path-parameters" type="boolean" default="false" toc={true}>
Whether to include path parameters within the generated in-lined request.
</ParamField>

<ParamField path="settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
<ParamField path="prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
Whether to prefer undiscriminated unions with literals.
</ParamField>

<ParamField path="settings.only-include-referenced-schemas" type="boolean" default="false" toc={true}>
<ParamField path="only-include-referenced-schemas" type="boolean" default="false" toc={true}>
Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).
</ParamField>

<ParamField path="settings.respect-nullable-schemas" type="boolean" default="false" toc={true}>
<ParamField path="respect-nullable-schemas" type="boolean" default="false" toc={true}>
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
</ParamField>

<ParamField path="settings.object-query-parameters" type="boolean" toc={true}>
<ParamField path="object-query-parameters" type="boolean" toc={true}>
Enables parsing deep object query parameters.
</ParamField>

<ParamField path="settings.respect-readonly-schemas" type="boolean" toc={true}>
<ParamField path="respect-readonly-schemas" type="boolean" toc={true}>
Enables exploring readonly schemas in OpenAPI specifications.
</ParamField>

<ParamField path="settings.respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
<ParamField path="respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
Enables respecting forward compatible enums in OpenAPI specifications.
</ParamField>

<ParamField path="settings.use-bytes-for-binary-response" type="boolean" toc={true}>
<ParamField path="use-bytes-for-binary-response" type="boolean" toc={true}>
Enables using the `bytes` type for binary responses. Defaults to file stream.
</ParamField>

<ParamField path="settings.default-form-parameter-encoding" type="FormParameterEncoding" default="json" toc={true}>
<ParamField path="default-form-parameter-encoding" type="FormParameterEncoding" default="json" toc={true}>
The default encoding of form parameters. Options: `form`, `json`.
</ParamField>

<ParamField path="settings.additional-properties-defaults-to" type="boolean" default="false" toc={true}>
<ParamField path="additional-properties-defaults-to" type="boolean" default="false" toc={true}>
Configure what `additionalProperties` should default to when not explicitly defined on a schema.
</ParamField>

<ParamField path="settings.type-dates-as-strings" type="boolean" default="true" toc={true}>
<ParamField path="type-dates-as-strings" type="boolean" default="true" toc={true}>
If true, convert strings with format date to strings. If false, convert to dates.
</ParamField>

<ParamField path="settings.preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
<ParamField path="preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
If true, preserve oneOf structures with a single schema. If false, unwrap them.
</ParamField>

<ParamField path="settings.filter.endpoints" type="list<string>" toc={true}>
<ParamField path="filter.endpoints" type="list<string>" toc={true}>
Endpoints to include in the generated SDK (e.g., "POST /users").
</ParamField>

<ParamField path="settings.example-generation.request.max-depth" type="integer" toc={true}>
<ParamField path="example-generation.request.max-depth" type="integer" toc={true}>
Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.
</ParamField>

<ParamField path="settings.example-generation.response.max-depth" type="integer" toc={true}>
<ParamField path="example-generation.response.max-depth" type="integer" toc={true}>
Controls the maximum depth for which optional properties will have examples generated in responses.
</ParamField>

Expand All @@ -234,35 +242,35 @@ api:
respect-nullable-schemas: true
```

<ParamField path="specs[].asyncapi" type="string" required={true} toc={true}>
<ParamField path="asyncapi" type="string" required={true} toc={true}>
Path to the AsyncAPI specification file.
</ParamField>

<ParamField path="specs[].origin" type="string" toc={true}>
<ParamField path="origin" type="string" toc={true}>
URL of the API definition origin for polling updates.
</ParamField>

<ParamField path="specs[].overrides" type="string" toc={true}>
<ParamField path="overrides" type="string" toc={true}>
Path to AsyncAPI overrides file.
</ParamField>

<ParamField path="specs[].namespace" type="string" toc={true}>
<ParamField path="namespace" type="string" toc={true}>
Namespace for the specification.
</ParamField>

<ParamField path="specs[].settings" type="AsyncAPISettingsSchema" toc={true}>
<ParamField path="settings" type="AsyncAPISettingsSchema" toc={true}>
AsyncAPI-specific generation settings.
</ParamField>

<ParamField path="settings.message-naming" type="MessageNamingSettingsSchema" default="v1" toc={true}>
<ParamField path="message-naming" type="MessageNamingSettingsSchema" default="v1" toc={true}>
What version of message naming to use for AsyncAPI messages. Options: `v1`, `v2`.
</ParamField>

<ParamField path="settings.title-as-schema-name" type="boolean" default="true" toc={true}>
<ParamField path="title-as-schema-name" type="boolean" default="true" toc={true}>
Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern.
</ParamField>

<ParamField path="settings.respect-nullable-schemas" type="boolean" default="false" toc={true}>
<ParamField path="respect-nullable-schemas" type="boolean" default="false" toc={true}>
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
</ParamField>

Expand All @@ -277,37 +285,37 @@ api:
local-generation: true
```

<ParamField path="specs[].proto" type="ProtobufDefinitionSchema" required={true} toc={true}>
<ParamField path="sproto" type="ProtobufDefinitionSchema" required={true} toc={true}>
Protocol Buffers configuration.
</ParamField>

<ParamField path="specs[].proto.target" type="string" toc={true}>
<ParamField path="target" type="string" toc={true}>
Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`).
</ParamField>

<ParamField path="specs[].proto.root" type="string" required={true} toc={true}>
<ParamField path="root" type="string" required={true} toc={true}>
Path to the `.proto` directory root (e.g., `proto`).
</ParamField>

<ParamField path="specs[].proto.overrides" type="string" toc={true}>
<ParamField path="overrides" type="string" toc={true}>
Path to the overrides configuration.
</ParamField>

<ParamField path="specs[].proto.local-generation" type="boolean" toc={true}>
<ParamField path="local-generation" type="boolean" toc={true}>
Whether to compile `.proto` files locally. Defaults to remote generation.
</ParamField>

#### OpenRPC

<ParamField path="specs[].openrpc" type="string" required={true} toc={true}>
<ParamField path=".openrpc" type="string" required={true} toc={true}>
Path to the OpenRPC specification file.
</ParamField>

<ParamField path="specs[].overrides" type="string" toc={true}>
<ParamField path="overrides" type="string" toc={true}>
Path to OpenRPC overrides file.
</ParamField>

<ParamField path="specs[].namespace" type="string" toc={true}>
<ParamField path="namespace" type="string" toc={true}>
Namespace for the specification.
</ParamField>

Expand All @@ -319,7 +327,7 @@ api:
conjure: "./conjure-api.yml"
```

<ParamField path="specs.conjure" type="string" toc={true}>
<ParamField path="conjure" type="string" toc={true}>
Path to Conjure specification file.
</ParamField>

Expand Down
3 changes: 3 additions & 0 deletions fern/products/sdks/sdks.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down