Reference

generators.yml configuration schema

The generators.yml file configures how Fern generates SDKs from your API specification, including which languages to generate, where to publish them, and how to customize each SDK.

generators.yml
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      namespace: "v1"
5      settings:
6        title-as-schema-name: true
7        inline-path-parameters: false
8        respect-forward-compatible-enums: true
9
10whitelabel:
11  github:
12    username: "my-org"
13    email: "sdk@mycompany.com"
14    token: "ghp_xxxxxxxxxxxx"
15
16metadata:
17  description: "Official SDK for MyAPI"
18  authors:
19    - name: "SDK Team"
20      email: "sdk@mycompany.com"
21
22readme:
23  introduction: "Welcome to the MyAPI SDK"
24  apiReferenceLink: "https://docs.myapi.com"
25  defaultEndpoint:
26    method: "GET"
27    path: "/users"
28  features:
29    authentication:
30      - "POST /auth/login"
31      - "GET /auth/profile"
32    users:
33      - "GET /users"
34      - "POST /users"
35
36default-group: "production"
37
38groups:
39  production:
40    generators:
41      - name: fernapi/fern-typescript-node-sdk
42        version: 0.9.0
43      - name: fernapi/fern-python-sdk
44        version: 2.0.0

auth-schemes

Define authentication methods for your API that your endpoints can reference. Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication.

Alternatively, you can define authentication for individual SDKs.

generators.yml
1auth-schemes:
2  # User-defined scheme name - OAuth with minimal configuration
3  simple-oauth:
4    scheme: oauth
5    type: client-credentials
6    get-token:
7      endpoint: "auth.token"
8    
9  # User-defined scheme name - Header auth with custom configuration
10  custom-header:
11    name: "Custom Auth"
12    header: "X-Custom-Auth"
13    prefix: "Custom "
14    env: "CUSTOM_TOKEN"
15    
16  # User-defined scheme name - Basic auth
17  http-basic:
18    scheme: basic
19    
20  # User-defined scheme name - Bearer token
21  jwt-bearer:
22    scheme: bearer

Configure HTTP Basic authentication using username and password credentials.

1auth-schemes:
2  basic-auth: # User-defined scheme name
3    scheme: basic
4    username:
5      name: "Username"
6      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
7    password:
8      name: "Password"
9      env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
scheme
'basic'Required

Must be set to "basic" for Basic authentication schemes.

username
object

Configuration for the username credential.

username.name
string

Custom parameter name for the username in the generated SDK. If not specified, defaults to "username". Use this to provide more descriptive or domain-specific parameter names like "clientId", "userEmail", or "merchantId".

password
object

Configuration for the password credential.

password.name
string

Custom parameter name for the password in the generated SDK. If not specified, defaults to "password". Use this to provide more descriptive or domain-specific parameter names like "clientSecret", "apiKey", or "merchantKey".

username.env, password.env
string

Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don’t need to explicitly provide the username parameter. Follow naming conventions like YOUR_APP_USERNAME or SERVICE_CLIENT_ID.

Configure Bearer token authentication for API access.

1auth-schemes:
2  bearer-token: # User-defined scheme name
3    scheme: bearer
4    token:
5      name: "Access Token"
6      env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
scheme
'bearer'Required

Must be set to "bearer" for Bearer token authentication schemes.

token
object

Configuration for the bearer token.

token.name
string

A descriptive name for the token.

token.env
string

Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Configure OAuth 2.0 client credentials authentication.

1auth-schemes:
2  my-oauth: # User-defined scheme name
3    scheme: oauth
4    type: client-credentials
5    scopes:
6      - "read:users"
7      - "write:users"
8    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
9    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
10    token-prefix: "Bearer"
11    token-header: "Authorization"
12    get-token:
13      endpoint: "auth.get_token"
14      request-properties:
15        client-id: "clientId"
16        client-secret: "clientSecret"
17        scopes: "scope"
18      response-properties:
19        access-token: "access_token"
20        expires-in: "expires_in"
21        refresh-token: "refresh_token"
22    refresh-token:
23      endpoint: "auth.refresh_token"
24      request-properties:
25        refresh-token: "refreshToken"
26      response-properties:
27        access-token: "access_token"
28        expires-in: "expires_in"
29        refresh-token: "refresh_token"
scheme
'oauth'Required

Must be set to "oauth" for OAuth authentication schemes.

type
literal<'client-credentials'>Required

The OAuth flow type. Currently only "client-credentials" is supported.

scopes
list<string>

List of OAuth scopes to request during authentication.

client-id-env
string

Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.

client-secret-env
string

Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.

token-prefix
stringDefaults to Bearer

Sets the token header value prefix.

token-header
stringDefaults to Authorization

Sets the token header key name.

get-token

Configuration for the token acquisition endpoint.

1get-token:
2  endpoint: "auth.get_token"
3  request-properties:
4    client-id: "clientId"
5    client-secret: "clientSecret"
6  response-properties:
7    access-token: "access_token"
8    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to get the access token, such as 'auth.get_token'.

request-properties
object

Customizes the property names used in the token request.

client-id
string

The property name for the client ID in the request.

client-secret
string

The property name for the client secret in the request.

scopes
string

The property name for the scopes in the request.

response-properties
object

Maps custom property names in your OAuth token response (e.g., if your API returns accessToken instead of access_token).

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

refresh-token

Configuration for the token refresh endpoint.

1refresh-token:
2  endpoint: "auth.refresh_token"
3  request-properties:
4    refresh-token: "refreshToken"
5  response-properties:
6    access-token: "access_token"
7    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to refresh the access token, such as 'auth.refresh_token'.

request-properties
object

Maps custom property names in your refresh token request.

refresh-token
stringRequired

The property name for the refresh token in the request.

response-properties
object

Maps custom property names in your refresh token response.

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

api

Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it. For Fern Definition, no API reference is needed – Fern automatically detects your spec.

generators.yml
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      namespace: "v1"
5      settings:
6        title-as-schema-name: true
7        inline-path-parameters: false
8    - asyncapi: "./events.yml"
9      namespace: "events"
10  headers:
11    Authorization: "Bearer ${API_TOKEN}"
12  environments:
13    production: "https://api.prod.com"
14    staging: "https://api.staging.com"
auth
object

Authentication configuration for the API.

headers
string or list of objects

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.

generators.yml
1api:
2  headers:
3    Authorization: "Bearer ${API_TOKEN}"
4    X-App-Version: "1.0.0"
generators.yml
1api:
2  - openapi: ./path/to/openapi
3    headers: 
4      X-Version: 
5        # The variable name to use in generated SDK code. 
6        # If not specified, uses the header name.
7        name: version 
8        # The type of the header value for code generation 
9        # (e.g., "string", "literal<'value'>", "number").
10        type: literal<"1234">
environments
object

Environment configurations for different deployment targets.

Specification types

generators.yml
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      origin: "https://api.example.com/openapi.json"
5      overrides: "./openapi-overrides.yml"
6      namespace: "v1"
7      settings:
8        title-as-schema-name: true
9        inline-path-parameters: false
10        inline-all-of-schemas: true
11        prefer-undiscriminated-unions-with-literals: true
12        filter:
13          endpoints: ["POST /users", "GET /users/{id}"]
14        example-generation:
15          request:
16            max-depth: 2
openapi
stringRequired

Path to the OpenAPI specification file.

origin
string

URL of the API definition origin for pulling updates. For instructions on how to set up automatic syncing, refer to Sync your OpenAPI specification.

overrides
string

Path to OpenAPI overrides file.

namespace
string

Namespace for the specification. Useful for configuring a single package with multiple API versions.

settings
object

OpenAPI-specific generation settings.

settings.title-as-schema-name
booleanDefaults to true

Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.

settings.inline-path-parameters
booleanDefaults to false

Whether to include path parameters within the generated in-lined request.

settings.inline-all-of-schemas
booleanDefaults to false

Whether to inline allOf schemas during code generation. When true, Fern recursively visits allOf schema definitions and inlines them into the child schema. When false, allOf schemas are extended through inheritance.

Enabling this setting allows child schemas to override parent property requirements. For example, a child schema can mark a parent’s required property as optional. Without this setting, Fern ignores the child schema’s optional declaration and preserves the parent schema’s requirement instead.

settings.prefer-undiscriminated-unions-with-literals
booleanDefaults to false

Whether to prefer undiscriminated unions with literals.

settings.only-include-referenced-schemas
booleanDefaults to false

Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).

settings.respect-nullable-schemas
booleanDefaults to false

Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.

settings.object-query-parameters
boolean

Enables parsing deep object query parameters.

settings.respect-readonly-schemas
boolean

Enables exploring readonly schemas in OpenAPI specifications.

settings.respect-forward-compatible-enums
booleanDefaults to false

Enables respecting forward compatible enums in OpenAPI specifications.

settings.use-bytes-for-binary-response
boolean

Enables using the bytes type for binary responses. Defaults to file stream.

settings.default-form-parameter-encoding
stringDefaults to json

The default encoding of form parameters. Options: form, json.

settings.additional-properties-defaults-to
booleanDefaults to false

Configure what additionalProperties should default to when not explicitly defined on a schema.

settings.type-dates-as-strings
booleanDefaults to true

If true, convert strings with format date to strings. If false, convert to dates.

settings.preserve-single-schema-oneof
booleanDefaults to false

If true, preserve oneOf structures with a single schema. If false, unwrap them.

settings.filter.endpoints
list of strings

Endpoints to include in the generated SDK (e.g., “POST /users”).

settings.example-generation.request.max-depth
integer

Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.

settings.example-generation.response.max-depth
integer

Controls the maximum depth for which optional properties will have examples generated in responses.

settings.coerce-enums-to-literals
booleanDefaults to true

Controls whether enums are converted to literal types during code generation. When set to false, enums are preserved as enums rather than being converted to literal types. This is useful when you want to maintain the original enum structure from your OpenAPI specification.

settings.idiomatic-request-names
booleanDefaults to false

Controls the naming convention for autogenerated request names. When enabled, places the verb before the noun in request names (e.g., UsersListRequest becomes ListUsersRequest), following more idiomatic naming patterns.

Disabled by default to maintain backwards compatibility.

settings.resolve-aliases
booleanDefaults to false

Inlines type aliases to simplify your generated SDK. When enabled, reduces unnecessary type definitions by replacing simple aliases with their underlying types directly. Useful for OpenAPI specs with many primitive or simple type aliases.

Set to true to inline all aliases, or use an object with an except array to preserve specific type aliases:

1settings:
2  # Inline all aliases
3  resolve-aliases: true
4
5  # Or preserve specific aliases
6  resolve-aliases:
7    except:
8      - UserId
9      - OrganizationId
settings.group-environments-by-host
booleanDefaults to false

When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.

1api:
2  specs:
3    - asyncapi: "./asyncapi.yml"
4      origin: "https://api.example.com/asyncapi.json"
5      overrides: "./asyncapi-overrides.yml"
6      namespace: "events"
7      settings:
8        message-naming: "v2"
9        title-as-schema-name: false
10        respect-nullable-schemas: true
asyncapi
stringRequired

Path to the AsyncAPI specification file.

origin
string

URL of the API definition origin for pulling updates.

overrides
string

Path to AsyncAPI overrides file.

namespace
string

Namespace for the specification. Useful for configuring a single package with multiple API versions.

settings
object

AsyncAPI-specific generation settings.

settings.message-naming
objectDefaults to v1

What version of message naming to use for AsyncAPI messages. Options: v1, v2.

settings.title-as-schema-name
booleanDefaults to true

Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern.

settings.respect-nullable-schemas
booleanDefaults to false

Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.

settings.group-environments-by-host
booleanDefaults to false

When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.

generators.yml
1api:
2  specs:
3    - proto:
4        root: "./proto"
5        target: "proto/service/v1/service.proto"
6        local-generation: true
root
stringRequired

Path to the .proto directory root (e.g., proto). Must be specified up to where the package starts. For example, if your package is package.test.v1 at the file path protos/package/test/v1/test_file.proto, the root should be protos/

target
string

Path to the target .proto file (e.g., proto/user/v1/user.proto). Omit to generate docs for the entire root folder.

overrides
string

Path to the overrides configuration file. Used for SDK generation only, not for documentation generation.

local-generation
booleanDefaults to false

Whether to compile .proto files locally. Defaults to remote generation (false).

.openrpc
stringRequired

Path to the OpenRPC specification file.

overrides
string

Path to OpenRPC overrides file.

namespace
string

Namespace for the specification.

generators.yml
1api:
2  specs:
3    conjure: "./conjure-api.yml"
conjure
string

Path to Conjure specification file.

whitelabel

Configuration for publishing generated SDKs without Fern branding. When enabled, removes all mentions of Fern from the generated code and allows publishing under your own brand.

generators.yml
1whitelabel:
2  github:
3    username: "company-github-username"
4    email: "my-email@example.com"
5    token: "ghp_xxxxxxxxxxxx"
username
stringRequired

The GitHub username that will be used for committing and publishing the whitelabeled SDK code to GitHub repositories. This should be the username of the account that has write access to your target repositories.

email
stringRequired

The email address associated with the GitHub account. This email will be used in Git commits when publishing the whitelabeled SDK code and should match the email configured in your GitHub account settings.

token
stringRequired

A GitHub Personal Access Token (PAT) with appropriate permissions for repository access. The token should have repo scope permissions to allow reading from and writing to your repositories for publishing whitelabeled SDKs.

metadata

Package metadata like description and authors that gets included in all generated SDKs. Alternatively, you can define metadata for individual SDKs.

generators.yml
1metadata:
2  description: "My API SDK"
3  authors:
4    - name: "John Doe"
5      email: "john@example.com"
6    - name: "Jane Smith"
7      email: "jane@example.com"
description
string

A brief description of the SDK that will be included in package metadata. This description helps users understand what your SDK does when they discover it in package repositories.

authors

A list of authors who will be credited in the generated SDK’s package metadata.

name
stringRequired

The full name of the author to be credited in the SDK package metadata.

email
stringRequired

The email address of the author. This will be included in package metadata and may be used by package managers for contact information.

readme

Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation.

generators.yml
1readme:
2  bannerLink: "https://example.com/banner"
3  introduction: "Welcome to our API"
4  apiReferenceLink: "https://docs.example.com"
5  apiName: "Example Product"
6  disabledSections:
7    - "contributing"
8  defaultEndpoint:
9    method: "POST"
10    path: "/users"
11    stream: false
12  customSections:
13    - title: "Custom Section"
14      language: "java"
15      content: |
16        This is a custom section. Latest package info is {{ group }}:{{ artifact }}:{{ version }}.
17    - title: "Custom Section"
18      language: "typescript"
19      content: |
20        Custom section for {{ packageName }}
21    - title: "Another Custom Section"
22      language: "typescript"
23      content: |
24        A second custom section for {{ packageName }}
25  features:
26    authentication:
27      - method: "POST"
28        path: "/auth/login"
29      - "GET /auth/profile"
30    users:
31      - method: "GET"
32        path: "/users"
33      - method: "POST"
34        path: "/users"
string

URL for a banner image or link that appears at the top of the README.

introduction
string

Custom introduction text that appears at the beginning of the README.

string

URL to your external API documentation or reference guide.

apiName
string

Name of the API that appears in the README. Will appear as Your Api Name SDK or Your Api Name API throughout the README. Defaults to organization name if not set.

disabledSections
list of strings

Sections to disable in the README. Supported values: "contributing".

features
list of objects

Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints.

Specifies which endpoint’s code snippet to showcase as the primary example in the README.

defaultEndpoint.method
stringRequired

HTTP method of the default endpoint (e.g., GET, POST, PUT, DELETE).

defaultEndpoint.path
stringRequired

Endpoint path for the default example (e.g., /users, /auth/login).

defaultEndpoint.stream
booleanDefaults to false

Whether the endpoint is a streaming endpoint. Defaults to false.

Define a custom section in the generated README for a specific SDK.

customSections.title
stringRequired

The title of the custom section as it will appear in the README.

customSections.language
'java' | 'typescript'Required

The target SDK language for this section. The custom section will only appear in README files generated for the specified language.

customSections.content
stringRequired

The Markdown content of the custom section. You can use template variables in the format {{ variable }} that will be dynamically replaced with values specific to each SDK language when the README is generated.

Available template variables by language:

LanguageVariableDescription
TypeScriptpackageNameName of your package, as specified in the package-name field
PythonpackageNameName of your package, as specified in the package-name field
GoownerThe owner of your Go module
GorepoThe repository where your Go module is published
GoversionSDK version
JavagroupMaven groupId from coordinate field
JavaartifactMaven artifactId from coordinate field
JavaversionSDK version
C#/.NETpackageNameName of your package, as specified in the package-name field
PHPpackageNameName of your package, as specified in the package-name field
RubypackageNameName of your package, as specified in the package-name field
SwiftgitUrlThe URL where your Swift package is published. For example, https://github.com/fern-api/basic-swift-sdk
SwiftminVersionSDK version

default-group

Which generator group to use when none is specified.

1default-group: "production"
default-group
string

groups

Organizes user-defined sets of generators, typically grouped by environment (like “production”, “staging”) or language (like “typescript”, “python”).

generators.yml
1groups:
2  typescript-sdk: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0
7        output:
8          location: npm
9          package-name: "@myorg/api-sdk"
10          token: "${NPM_TOKEN}"
11        github:
12          repository: your-organization/company-typescript
13          mode: "pull-request"
14    metadata:
15      description: "TypeScript SDK for MyAPI"
16      authors:
17        - name: "SDK Team"
18          email: "sdk@myorg.com"
19    reviewers:
20      teams:
21        - name: "sdk-team"
audiences
list of strings

Target audiences for this generator group (e.g., “external”, “internal”)

reviewers

Set code reviewers for an individual SDK. Alternatively, you can configure reviewers globally for all SDKs.

generators.yml
1reviewers:
2  teams:
3    - name: "sdk-team"
4    - name: "api-team"
5  users:
6    - name: "john-doe"
7    - name: "jane-smith"
teams
list of strings

GitHub team names that should review generated code.

users
list of strings

GitHub users that should review generated code.

teams.name
stringRequired

Name of a GitHub team.

users.name
stringRequired

Name of a GitHub user.

generators

Generator settings for a specific group.

generators.yml
1groups:
2  typescript-sdk: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0
7        smart-casing: true
name
stringRequired

The Fern generator package name (e.g., fernapi/fern-typescript-node-sdk)

version
stringRequired

Specific version of the generator to use

smart-casing
booleanDefaults to false

Enables intelligent case conversion that preserves numbers and common programming patterns:

  • Numbers stay intact (e.g., v2 instead of v_2, getUsersV2 instead of getUsersV_2)
  • Initialisms are preserved (e.g., CustomerID instead of CustomerId)
  • Acronyms remain correct (e.g., HTTPSConnection stays HTTPSConnection)

config

Language-specific configuration options.

generators.yml
1groups:
2  ts-sdk: # Typescript SDK group
3    generators:
4      - name: fernapi/fern-typescript-sdk
5        version: 3.8.0
6        config: # TypeScript-specific config options
7          namespaceExport: AcmePayments
8          noSerdeLayer: false
TypeScript
Python
Go
Java
.NET
PHP
Ruby
Swift

output

Where to publish the generated SDK.

generators.yml
1groups:
2  typescript-sdk: # User-defined name
3    audiences: ["external"]
4    generators:
5      - name: fernapi/fern-typescript-node-sdk
6        version: 0.9.0
7        output:
8          location: npm
9          package-name: "@myorg/api-sdk"
10          token: "${NPM_TOKEN}"

Publish TypeScript SDKs to the npm registry.

generators.yml
1output:
2  location: npm
3  package-name: "@myorg/api-sdk"
4  token: "${NPM_TOKEN}"
location
'npm'Required

Set to “npm” for NPM publishing

url
stringDefaults to npmjs.com

Custom NPM registry URL

package-name
stringRequired

NPM package name (e.g., “@myorg/api-sdk”)

token
string

NPM authentication token for publishing

Publish Java SDKs to Maven repository.

generators.yml
1output:
2  location: maven
3  coordinate: "com.myorg:api-sdk"
4  username: "${MAVEN_USERNAME}"
5  password: "${MAVEN_PASSWORD}"
6  signature:
7    keyId: "ABC123"
8    password: "${GPG_PASSWORD}"
9    secretKey: "${GPG_SECRET_KEY}"
location
'maven'Required

Set to “maven” for Maven publishing

url
stringDefaults to npmjs.com

Maven repository URL (optional, defaults to Maven Central)

coordinate
stringRequired

Maven artifact coordinate in “groupId:artifactId” format

username
string

Repository authentication username

password
string

Repository authentication password

signature
object

GPG signature configuration for package signing

signature.keyId
stringRequired

GPG key ID for package signing

signature.password
stringRequired

GPG key password

signature.secretKey
stringRequired

GPG secret key content

Publish Python SDKs to Python Package Index.

generators.yml
1output:
2  location: pypi
3  package-name: "myorg-api-sdk"
4  token: "${PYPI_TOKEN}"
5  metadata:
6    keywords: ["api", "sdk", "client"]
7    documentation-link: "https://docs.myorg.com"
8    homepage-link: "https://myorg.com"
location
'pypi'Required

Set to “pypi” for PyPI publishing

url
string

Custom PyPI registry URL (optional, defaults to PyPI)

package-name
stringRequired

Python package name (e.g., “myorg-api-sdk”)

token
string

PyPI authentication token for publishing

username
string

PyPI username (alternative to token authentication)

password
string

PyPI password (alternative to token authentication)

metadata
objecta

Additional PyPI-specific metadata for the package

metadata.keywords
list of string

Package keywords for PyPI search and discovery

metadata.documentation-link
string

Link to package documentation

metadata.homepage-link
string

Link to project homepage

Publish .NET SDKs to NuGet repository.

generators.yml
1output:
2  location: nuget
3  package-name: "MyOrg.ApiSdk"
4  api-key: "${NUGET_API_KEY}"
location
'nuget'Required

Set to “nuget” for NuGet publishing

url
string

Custom NuGet feed URL (optional, defaults to nuget.org)

package-name
stringRequired

NuGet package name (e.g., “MyOrg.ApiSdk”)

api-key
string

NuGet API key for publishing to the feed

Publish Ruby SDKs to RubyGems registry.

generators.yml
1output:
2  location: rubygems
3  package-name: "myorg_api_sdk"
4  api-key: "${RUBYGEMS_API_KEY}"
location
'rubygems'Required

Set to “rubygems” for RubyGems publishing

url
string

Custom RubyGems registry URL (optional, defaults to rubygems.org)

package-name
stringRequired

Ruby gem package name (e.g., “myorg_api_sdk”)

api-key
string

RubyGems API key for publishing (requires “Push rubygem” permission)

Note: RubyGems API keys need “Push rubygem” permission and ideally “index” and “yank rubygem” permissions. If MFA is enabled, ensure MFA settings don’t require MFA for API key usage.

Publish API collections to Postman workspace.

generators.yml
1output:
2  location: postman
3  api-key: "${POSTMAN_API_KEY}"
4  workspace-id: "12345678-1234-1234-1234-123456789abc"
5  collection-id: "87654321-4321-4321-4321-cba987654321"
location
'postman'Required

Set to “postman” for Postman publishing

api-key
stringRequired

Postman API key for workspace access

workspace-id
stringRequired

Target Postman workspace ID where collection will be published

collection-id
string

Existing collection ID to update (creates new collection if not specified)

Save generated SDKs to local file system instead of publishing.

generators.yml
1output:
2  location: local-file-system
3  path: "./generated-sdks/typescript"
location
'local-file-system'Required

Set to “local-file-system” for local output

path
stringRequired

Local directory path where generated files will be saved

github

Specify how your SDKs are generated in GitHub using the github configuration. Designate the mode to specifiy how Fern handles your code changes. For all of the modes, you must specify the GitHub repository in which you want to store your SDK code. You can also configure a branch name, license, and reviewers.

Make sure the Fern GitHub app is installed on your destination repository

Fern generates your code, commits to a new branch, and opens a PR for review. To publish, you must merge the PR and tag a GitHub release.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        github: 
7          repository: "your-org/your-repo-name"
8          mode: "pull-request"
repository
stringRequired

Name of your repository in GitHub.

mode
'pull-request'
branch
string

Name of your branch in GitHub.

license
'MIT' | 'Apache-2.0' | 'Custom License Name'

Software license for the generated SDK.

reviewers
list of objects

Specify which teams and users should review generated code. See reviewers configuration.

Fern generates your code and pushes it to the branch you specify.

1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        github: 
7          repository: "your-org/your-repo-name"
8          mode: "push"
9          branch: "your-branch-name" # required for `mode: push`
repository
stringRequired

Name of your repository in GitHub.

mode
'push'
branch
stringRequired

Name of your branch in GitHub.

license
'MIT' | 'Apache-2.0' | 'Custom License Name'

Software license for the generated SDK.

reviewers
{ teams: list<string>, users: list<string> }

Specify which teams and users should review generated code. See reviewers configuration.

metadata

Specify metadata for an individual SDK. Alternatively, you can configure metadata globally for all SDKs.

generators.yml
1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        metadata: 
7          package-description: "Description of your SDK"
8          email: "sdk@example.com"
9          reference-url: "https://docs.example.com/sdks"
10          license: "MIT"
package-description
string

A brief description of what your generated SDK does and its key features. This appears in the package.json description field and package registry listings.

email
string

Contact email for the package maintainer or support team.

reference-url
string

URL pointing to comprehensive documentation, API reference, or getting started guide for the SDK.

author
string

Name of the individual developer, team, or organization that created and maintains the SDK.

license
'MIT' | 'Apache-2.0' | 'Custom License Name'

Software license for the generated SDK.

snippets

Configures snippets for a particular generator.

generators.yml
1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        snippets: 
7          path: "./snippets"
path
stringRequired

The path to the generated snippets file.

Override API authentication settings

Override authentication settings in your API spec for a specific SDK using the api configuration.

Reference a pre-defined authentication scheme by name.

generators.yml
1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          auth: "bearer-token"
auth
string | { scheme: string }

The authentication scheme to use. Can be either a string reference ("bearer-token") or scheme object (scheme: "bearer-token").

Allow users to authenticate with any of several methods:

generators.yml
1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          auth:
8            any:
9              - "api-key"
10              - "bearer-token"
11              - scheme: "oauth-flow"
any
list<string | { scheme: string }>Required

A list of authentication schemes where users can choose any one method. Each item can be either a string reference ("api-key") or scheme object (scheme: "api-key").

Define a custom authentication schemes using auth-schemes. You define a name for your custom scheme, and then specify the authentication method (header, basic, bearer, or oauth).

generators.yml
1groups: 
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5      ...
6        api:
7          auth-schemes:
8            bearer:  # User-defined name for your auth schema
9              scheme: "bearer"
10              token:
11                name: "token"
12                env: "BEARER_TOKEN"

Configure authentication using custom HTTP headers, such as API keys or tokens.

1auth-schemes:
2  api-key: # User-defined scheme name
3    name: "API Key Authentication"
4    header: "X-API-Key"
5    type: "string"
6    prefix: "ApiKey "
7    env: "MY_API_KEY" # SDK will auto-scan this environment variable
header
stringRequired

The name of the HTTP header to use for authentication.

name
string

A descriptive name for this authentication scheme.

type
stringDefaults to string

The type of the header value.

prefix
string

A prefix to prepend to the header value (e.g., "Bearer " or "Token ").

env
string

Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Configure HTTP Basic authentication using username and password credentials.

1auth-schemes:
2  basic-auth: # User-defined scheme name
3    scheme: basic
4    username:
5      name: "Username"
6      env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
7    password:
8      name: "Password"
9      env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
scheme
'basic'Required

Must be set to "basic" for Basic authentication schemes.

username
object

Configuration for the username credential.

username.name
string

Custom parameter name for the username in the generated SDK. If not specified, defaults to "username". Use this to provide more descriptive or domain-specific parameter names like "clientId", "userEmail", or "merchantId".

password
object

Configuration for the password credential.

password.name
string

Custom parameter name for the password in the generated SDK. If not specified, defaults to "password". Use this to provide more descriptive or domain-specific parameter names like "clientSecret", "apiKey", or "merchantKey".

username.env, password.env
string

Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don’t need to explicitly provide the username parameter. Follow naming conventions like YOUR_APP_USERNAME or SERVICE_CLIENT_ID.

Configure Bearer token authentication for API access.

1auth-schemes:
2  bearer-token: # User-defined scheme name
3    scheme: bearer
4    token:
5      name: "Access Token"
6      env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
scheme
'bearer'Required

Must be set to "bearer" for Bearer token authentication schemes.

token
object

Configuration for the bearer token.

token.name
string

A descriptive name for the token.

token.env
string

Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Configure OAuth 2.0 client credentials authentication.

1auth-schemes:
2  my-oauth: # User-defined scheme name
3    scheme: oauth
4    type: client-credentials
5    scopes:
6      - "read:users"
7      - "write:users"
8    client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
9    client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
10    token-prefix: "Bearer"
11    token-header: "Authorization"
12    get-token:
13      endpoint: "auth.get_token"
14      request-properties:
15        client-id: "clientId"
16        client-secret: "clientSecret"
17        scopes: "scope"
18      response-properties:
19        access-token: "access_token"
20        expires-in: "expires_in"
21        refresh-token: "refresh_token"
22    refresh-token:
23      endpoint: "auth.refresh_token"
24      request-properties:
25        refresh-token: "refreshToken"
26      response-properties:
27        access-token: "access_token"
28        expires-in: "expires_in"
29        refresh-token: "refresh_token"
scheme
'oauth'Required

Must be set to "oauth" for OAuth authentication schemes.

type
literal<'client-credentials'>Required

The OAuth flow type. Currently only "client-credentials" is supported.

scopes
list<string>

List of OAuth scopes to request during authentication.

client-id-env
string

Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.

client-secret-env
string

Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.

token-prefix
stringDefaults to Bearer

Sets the token header value prefix.

token-header
stringDefaults to Authorization

Sets the token header key name.

get-token

Configuration for the token acquisition endpoint.

1get-token:
2  endpoint: "auth.get_token"
3  request-properties:
4    client-id: "clientId"
5    client-secret: "clientSecret"
6  response-properties:
7    access-token: "access_token"
8    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to get the access token, such as 'auth.get_token'.

request-properties
object

Customizes the property names used in the token request.

client-id
string

The property name for the client ID in the request.

client-secret
string

The property name for the client secret in the request.

scopes
string

The property name for the scopes in the request.

response-properties
object

Maps custom property names in your OAuth token response (e.g., if your API returns accessToken instead of access_token).

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

refresh-token

Configuration for the token refresh endpoint.

1refresh-token:
2  endpoint: "auth.refresh_token"
3  request-properties:
4    refresh-token: "refreshToken"
5  response-properties:
6    access-token: "access_token"
7    expires-in: "expires_in"
endpoint
stringRequired

The endpoint to refresh the access token, such as 'auth.refresh_token'.

request-properties
object

Maps custom property names in your refresh token request.

refresh-token
stringRequired

The property name for the refresh token in the request.

response-properties
object

Maps custom property names in your refresh token response.

access-token
string

The property name for the access token in the response.

expires-in
string

The property name for the expires in property in the response.

refresh-token
string

The property name for the refresh token in the response.

reviewers

Set code reviewers globally for all SDKs. Alternatively, you can configure reviewers for individual SDKs.

generators.yml
1reviewers:
2  teams:
3    - name: "sdk-team"
4    - name: "api-team"
5  users:
6    - name: "john-doe"
7    - name: "jane-smith"
teams
list of strings

GitHub team names that should review generated code.

users
list of strings

GitHub users that should review generated code.

teams.name
stringRequired

Name of a GitHub team.

users.name
stringRequired

Name of a GitHub user.