diff --git a/fern/products/sdks/overview/csharp/configuration.mdx b/fern/products/sdks/overview/csharp/configuration.mdx index 38d9dea73..7b527d5b0 100644 --- a/fern/products/sdks/overview/csharp/configuration.mdx +++ b/fern/products/sdks/overview/csharp/configuration.mdx @@ -1,5 +1,5 @@ --- -title: .NET Configuration +title: .NET configuration description: Configuration options for the Fern .NET SDK. --- @@ -15,8 +15,6 @@ groups: client_class_name: YourApiClient ``` -## SDK configuration options - When enabled, allows handling of additional properties not explicitly defined in the API specification. This provides flexibility for APIs that may include extra fields in responses. diff --git a/fern/products/sdks/overview/go/configuration.mdx b/fern/products/sdks/overview/go/configuration.mdx index 55c696448..4ed14ea2b 100644 --- a/fern/products/sdks/overview/go/configuration.mdx +++ b/fern/products/sdks/overview/go/configuration.mdx @@ -1,5 +1,5 @@ --- -title: Go Configuration +title: Go configuration description: Configuration options for the Fern Go SDK. --- @@ -18,8 +18,6 @@ groups: path: ../generated/go ``` -## SDK Configuration Options - When enabled, ensures that all required properties are always included in API requests, even if they have default values or are otherwise optional in the implementation. diff --git a/fern/products/sdks/overview/java/configuration.mdx b/fern/products/sdks/overview/java/configuration.mdx index a88a46e7d..5afea6078 100644 --- a/fern/products/sdks/overview/java/configuration.mdx +++ b/fern/products/sdks/overview/java/configuration.mdx @@ -1,5 +1,5 @@ --- -title: Java Configuration +title: Java configuration description: Configuration options for the Fern Java SDK. --- You can customize the behavior of the Java SDK generator in `generators.yml`: @@ -14,8 +14,6 @@ groups: client-class-name: YourApiClient ``` -## SDK Configuration Options - Customizes the name of the base API exception class that all API-specific exceptions will extend. This allows you to define a custom base exception class name for better integration with your existing error handling patterns. diff --git a/fern/products/sdks/overview/php/configuration.mdx b/fern/products/sdks/overview/php/configuration.mdx index 78de344f9..990131feb 100644 --- a/fern/products/sdks/overview/php/configuration.mdx +++ b/fern/products/sdks/overview/php/configuration.mdx @@ -1,5 +1,5 @@ --- -title: PHP Configuration +title: PHP configuration description: Configuration options for the Fern PHP SDK. --- diff --git a/fern/products/sdks/overview/python/configuration.mdx b/fern/products/sdks/overview/python/configuration.mdx index 72c4a8c4e..22218e343 100644 --- a/fern/products/sdks/overview/python/configuration.mdx +++ b/fern/products/sdks/overview/python/configuration.mdx @@ -1,5 +1,5 @@ --- -title: Python Configuration +title: Python configuration description: Configuration options for the Fern Python SDK. --- @@ -23,8 +23,6 @@ groups: skip_validation: true ``` -## SDK Configuration Options - Additional modules or classes to export from the package's `__init__.py` file. This allows you to customize what's available when users import your package. diff --git a/fern/products/sdks/overview/ruby/configuration.mdx b/fern/products/sdks/overview/ruby/configuration.mdx index dfc1f8d54..44edbbb36 100644 --- a/fern/products/sdks/overview/ruby/configuration.mdx +++ b/fern/products/sdks/overview/ruby/configuration.mdx @@ -1,5 +1,5 @@ --- -title: Ruby Configuration +title: Ruby configuration description: Configuration options for the Fern Ruby SDK. --- @@ -15,8 +15,6 @@ groups: clientClassName: YourClientName ``` -## SDK Configuration Options - The name of the generated client class. This allows you to customize the class name that users will instantiate when using your SDK. diff --git a/fern/products/sdks/overview/swift/configuration.mdx b/fern/products/sdks/overview/swift/configuration.mdx index 8c063504c..9827663e6 100644 --- a/fern/products/sdks/overview/swift/configuration.mdx +++ b/fern/products/sdks/overview/swift/configuration.mdx @@ -18,8 +18,6 @@ groups: enableWireTests: false ``` -## SDK Configuration Options - The name of the generated client class. This allows you to customize the class name that users will instantiate when using your SDK. diff --git a/fern/products/sdks/overview/typescript/configuration.mdx b/fern/products/sdks/overview/typescript/configuration.mdx index 9332a7c42..0d8c20156 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -1,5 +1,5 @@ --- -title: TypeScript Configuration +title: TypeScript configuration description: Configuration options for the Fern TypeScript SDK. --- @@ -16,8 +16,6 @@ groups: noSerdeLayer: false ``` -## SDK configuration options - Allow fields that are not defined in object schemas. This only applies to serde. diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index cded12e7b..ea66f54f1 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -1,15 +1,13 @@ --- -title: generators.yml Configuration Schema +title: generators.yml configuration schema description: Reference for the generators.yml configuration --- 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. This document describes the complete configuration -schema for `generators.yml`. +how to customize each SDK. -```yaml -# Example generators.yml configuration +```yaml title="generators.yml" maxLines=10 api: specs: - openapi: "./openapi.yml" @@ -56,12 +54,13 @@ groups: version: 2.0.0 ``` -## auth-schemes -Define authentication methods for your API. Create named authentication schemes that your endpoints can reference. +## `auth-schemes` -Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. +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. -```yaml +Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). + +```yaml title="generators.yml" maxLines=10 auth-schemes: # User-defined scheme name - OAuth with minimal configuration simple-oauth: @@ -85,36 +84,34 @@ auth-schemes: jwt-bearer: scheme: bearer ``` - -### Header Authentication - + + - -### Basic Authentication - + + - -### Bearer Token Authentication - + + - -### OAuth Authentication - + + -#### get-token +#### `get-token` -#### refresh-token +#### `refresh-token` + + -## api +## `api` - Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it. +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](/sdks/overview/project-structure#generatorsyml). -```yaml +```yaml title="generators.yml" maxLines=10 api: specs: - openapi: "./openapi.yml" @@ -131,10 +128,6 @@ api: staging: "https://api.staging.com" ``` - - List of API specifications or Conjure configuration. - - Authentication configuration for the API. @@ -142,16 +135,19 @@ api: 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 + + + + ```yaml title="generators.yml" api: headers: Authorization: "Bearer ${API_TOKEN}" X-App-Version: "1.0.0" ``` + + - **Advanced configuration with type information:** - ```yaml + ```yaml title="generators.yml" api: - openapi: ./path/to/openapi headers: @@ -163,19 +159,21 @@ api: # (e.g., "string", "literal<'value'>", "number"). type: literal<"1234"> ``` + + Environment configurations for different deployment targets. -### Specification Types - -#### OpenAPI +### Specification types + + - -#### AsyncAPI + + ```yaml api: @@ -221,10 +219,10 @@ api: Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional. + + -#### Protocol Buffers - -```yaml +```yaml title="generators.yml" api: specs: - proto: @@ -233,27 +231,23 @@ api: local-generation: true ``` - - Protocol Buffers configuration. + + Path to the `.proto` directory root (e.g., `proto`). 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. + + Whether to compile `.proto` files locally. Defaults to remote generation (`false`). - -#### OpenRPC + + Path to the OpenRPC specification file. @@ -266,8 +260,8 @@ api: Namespace for the specification. - -#### Conjure + + ```yaml api: @@ -278,12 +272,14 @@ api: Path to Conjure specification file. + + -## whitelabel +## `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. -```yaml +```yaml title="generators.yml" whitelabel: github: username: "company-github-username" @@ -301,10 +297,10 @@ whitelabel: -## metadata -Package metadata like description and authors that gets included in generated SDKs. +## `metadata` +Package metadata like description and authors that gets included in all generated SDKs. Alternatively, you can [define metadata for individual SDKs](#metadata-2). -```yaml +```yaml title="generators.yml" metadata: description: "My API SDK" authors: @@ -318,7 +314,7 @@ metadata: 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 +### `authors` A list of authors who will be credited in the generated SDK's package metadata. @@ -329,14 +325,14 @@ metadata: The email address of the author. This will be included in package metadata and may be used by package managers for contact information. -## readme +## `readme` Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation. -## default-group -Which group to use when none is specified. +## `default-group` +Which generator group to use when none is specified. ```yaml default-group: "production" @@ -345,13 +341,13 @@ default-group: "production" -## groups +## `groups` Organizes user-defined sets of generators, typically grouped by environment (like "production", "staging") or language (like "typescript", "python"). -```yaml +```yaml title="generators.yml" maxLines=10 groups: - company-typescript: # User-defined name + typescript-sdk: # User-defined name audiences: ["external"] generators: - name: fernapi/fern-typescript-node-sdk @@ -377,26 +373,25 @@ groups: Target audiences for this generator group (e.g., "external", "internal") +### `reviewers` -### reviewers - -Who should review generated code for a specific group. +Set code reviewers for an individual SDK. Alternatively, you can [configure reviewers globally for all SDKs](#reviewers-4). -### generators +### `generators` -```yaml +Generator settings for a specific group. + +```yaml title="generators.yml" groups: - company-typescript: # User-defined name + typescript-sdk: # User-defined name audiences: ["external"] generators: - name: fernapi/fern-typescript-node-sdk version: 0.9.0 ``` -Individual generator settings within a group. - The Fern generator package name (e.g., fernapi/fern-typescript-node-sdk) @@ -405,13 +400,48 @@ The Fern generator package name (e.g., fernapi/fern-typescript-node-sdk) Specific version of the generator to use -#### output +#### `config` -Configuration for where and how to publish the generated SDK +Language-specific configuration options. -```yaml +```yaml title="generators.yml" +groups: + ts-sdk: # Typescript SDK group + generators: + - name: fernapi/fern-typescript-sdk + version: + config: # TypeScript-specific config options + namespaceExport: AcmePayments + noSerdeLayer: false +``` + + + + + + + + + + + + + + + + + + + + + +#### `output` + +Where to publish the generated SDK. + +```yaml title="generators.yml" groups: - company-typescript: # User-defined name + typescript-sdk: # User-defined name audiences: ["external"] generators: - name: fernapi/fern-typescript-node-sdk @@ -423,11 +453,11 @@ groups: ``` - + -Publish TypeScript/JavaScript SDKs to NPM registry. +Publish TypeScript SDKs to the npm registry. -```yaml +```yaml title="generators.yml" output: location: npm package-name: "@myorg/api-sdk" @@ -450,11 +480,11 @@ NPM package name (e.g., "@myorg/api-sdk") NPM authentication token for publishing - + Publish Java SDKs to Maven repository. -```yaml +```yaml title="generators.yml" output: location: maven coordinate: "com.myorg:api-sdk" @@ -502,11 +532,11 @@ GPG key password GPG secret key content - + Publish Python SDKs to Python Package Index. -```yaml +```yaml title="generators.yml" output: location: pypi package-name: "myorg-api-sdk" @@ -558,11 +588,11 @@ Link to project homepage - + Publish .NET SDKs to NuGet repository. -```yaml +```yaml title="generators.yml" output: location: nuget package-name: "MyOrg.ApiSdk" @@ -585,11 +615,11 @@ NuGet package name (e.g., "MyOrg.ApiSdk") NuGet API key for publishing to the feed - + Publish Ruby SDKs to RubyGems registry. -```yaml +```yaml title="generators.yml" output: location: rubygems package-name: "myorg_api_sdk" @@ -614,11 +644,11 @@ 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. -```yaml +```yaml title="generators.yml" output: location: postman api-key: "${POSTMAN_API_KEY}" @@ -642,11 +672,11 @@ Target Postman workspace ID where collection will be published Existing collection ID to update (creates new collection if not specified) - + Save generated SDKs to local file system instead of publishing. -```yaml +```yaml title="generators.yml" output: location: local-file-system path: "./generated-sdks/typescript" @@ -662,7 +692,7 @@ Local directory path where generated files will be saved -#### github +#### `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 @@ -767,11 +797,11 @@ Specify which teams and users should review generated code. See [reviewers confi -#### metadata +#### `metadata` -Specify metadata for your SDK generator. +Specify metadata for an individual SDK. Alternatively, you can [configure metadata globally for all SDKs](#metadata). -```yml {6-10} +```yml title="generators.yml" {6-10} groups: ts-sdk: generators: @@ -804,11 +834,11 @@ Name of the individual developer, team, or organization that created and maintai Software license for the generated SDK. -#### snippets +#### `snippets` Configures snippets for a particular generator. -```yml {6-8} +```yml title="generators.yml" {6-8} groups: ts-sdk: generators: @@ -822,18 +852,16 @@ groups: The path to the generated snippets file. -#### Override API Authentication Settings +#### Override API authentication settings -Override authentication settings in your API spec using the `api` configuration. -You can specify authentication schemes, reference existing auth configurations, -and set additional API-specific settings. +Override authentication settings in your API spec for a specific SDK using the `api` configuration. - + Reference a pre-defined authentication scheme by name. -```yml {6-7} +```yml title="generators.yml" {6-7} groups: ts-sdk: generators: @@ -847,11 +875,11 @@ groups: 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: -```yml {6-12} +```yml title="generators.yml" {6-12} groups: ts-sdk: generators: @@ -870,11 +898,11 @@ A list of authentication schemes where users can choose any one method. Each ite - + 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`). -```yml {8-12} +```yml title="generators.yml" {8-12} groups: ts-sdk: generators: @@ -910,11 +938,11 @@ groups: -##### get-token +##### `get-token` -##### refresh-token +##### `refresh-token` @@ -924,8 +952,8 @@ groups: -### reviewers +### `reviewers` -Who should review generated code for all groups. +Set code reviewers globally for all SDKs. Alternatively, you can [configure reviewers for individual SDKs](#reviewers). diff --git a/fern/products/sdks/snippets/readme-options.mdx b/fern/products/sdks/snippets/readme-options.mdx index f40e1c05c..a66798a53 100644 --- a/fern/products/sdks/snippets/readme-options.mdx +++ b/fern/products/sdks/snippets/readme-options.mdx @@ -1,4 +1,4 @@ -```yaml +```yaml title="generators.yml" maxLines=10 readme: bannerLink: "https://example.com/banner" introduction: "Welcome to our API" @@ -59,7 +59,8 @@ readme: Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints. -### Endpoint configuration + + Specifies which endpoint's code snippet to showcase as the primary example in the README. @@ -74,8 +75,8 @@ Specifies which endpoint's code snippet to showcase as the primary example in th Whether the endpoint is a streaming endpoint. Defaults to `false`. - -### Custom sections + + Define a custom section in the generated README for a specific SDK. @@ -106,4 +107,6 @@ Define a custom section in the generated README for a specific SDK. | Swift | `gitUrl` | The [URL](/sdks/generators/swift/publishing#verify-package-availability) where your Swift package is published. For example, `https://github.com/fern-api/basic-swift-sdk` | | Swift | `minVersion` | SDK version | - \ No newline at end of file + + + \ No newline at end of file diff --git a/fern/products/sdks/snippets/reviewers-params.mdx b/fern/products/sdks/snippets/reviewers-params.mdx index ee7a4e817..331fab394 100644 --- a/fern/products/sdks/snippets/reviewers-params.mdx +++ b/fern/products/sdks/snippets/reviewers-params.mdx @@ -1,5 +1,5 @@ -```yaml +```yaml title="generators.yml" reviewers: teams: - name: "sdk-team"