From 3f61de8a2e3c2865e4391d685091ddb318be9e43 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:26 +0000 Subject: [PATCH 1/7] Create readme.mdx based on issue #323 --- fern/products/sdks/pages/reference/readme.mdx | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 fern/products/sdks/pages/reference/readme.mdx diff --git a/fern/products/sdks/pages/reference/readme.mdx b/fern/products/sdks/pages/reference/readme.mdx new file mode 100644 index 00000000..89edb57f --- /dev/null +++ b/fern/products/sdks/pages/reference/readme.mdx @@ -0,0 +1,81 @@ +--- +title: "Customizing SDK READMEs" +description: "Learn how to customize the README.md files generated for your SDKs" +--- + +The README.md file is an essential part of any SDK package, providing users with key information about installation, usage, and configuration. Fern allows you to customize the README for each SDK generator. + +## Overview + +By default, Fern generates a standard README.md that includes: + +- Installation instructions +- Basic usage example +- Authentication setup +- Links to documentation + +You can customize this by adding README configuration in your `generators.yml` file. + +## Configuration + +Add README customization under the `readme` key for your generator: + +```yaml +generators: + - name: fernapi/fern-typescript-sdk + version: 0.7.1 + output: + location: local-file-system + path: ../generated/typescript + readme: + title: "Custom SDK Title" + description: "A TypeScript SDK for interacting with our API" + examples: + - title: "Basic Usage" + code: | + import { ApiClient } from "@company/sdk"; + + const client = new ApiClient({ + token: "YOUR_TOKEN" + }); + + const response = await client.users.get("123"); +``` + +## Available Options + + + Custom title for the README + + + + Description that appears below the title + + + + Array of code examples to include in the README. Each example should have: + - `title`: The section heading for the example + - `code`: The code snippet to display + + + + Override the package name shown in installation instructions + + + + Custom URL slug for documentation links + + +## Best Practices + +1. Keep examples concise but practical +2. Include common use cases +3. Show proper error handling +4. Demonstrate authentication setup +5. Link to full documentation for advanced usage + + + Changes to README configuration only affect newly generated SDKs. You'll need to regenerate your SDKs to see the updates. + + +For more detailed configuration options, see the [SDK README Reference](/sdks/reference/readme). \ No newline at end of file From 3e2a1171ae96265a2aad3d07ced296c5ee999100 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:27 +0000 Subject: [PATCH 2/7] Add Readme page to navigation --- fern/products/sdks/sdks.yml | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index c771d752..82a6e3d8 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -18,6 +18,8 @@ navigation: slug: capabilities - link: Customer Showcase href: https://buildwithfern.com/showcase + - page: Readme + path: ./pages/reference/readme.mdx - section: Generators contents: - section: TypeScript @@ -41,8 +43,6 @@ navigation: slug: custom-code - changelog: ./overview/typescript/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: Python contents: - page: Quickstart @@ -59,12 +59,10 @@ navigation: path: ./overview/python/publishing-to-pypi.mdx slug: publishing - page: Adding custom code - path: ./overview/python/custom-code.mdx + path: ./overview/python/custom-code.mdx slug: custom-code - changelog: ./overview/python/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: Go contents: - page: Quickstart @@ -81,12 +79,10 @@ navigation: path: ./overview/go/publishing-to-go-package-manager.mdx slug: publishing - page: Adding custom code - path: ./overview/go/custom-code.mdx + path: ./overview/go/custom-code.mdx slug: custom-code - changelog: ./overview/go/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: Java contents: - page: Quickstart @@ -107,8 +103,6 @@ navigation: slug: custom-code - changelog: ./overview/java/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: .NET slug: csharp contents: @@ -131,8 +125,6 @@ navigation: slug: custom-code - changelog: ./overview/csharp/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: PHP contents: - page: Quickstart @@ -154,8 +146,6 @@ navigation: slug: custom-code - changelog: ./overview/php/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - section: Ruby contents: - page: Quickstart @@ -177,13 +167,11 @@ navigation: slug: custom-code - changelog: ./overview/ruby/changelog slug: changelog - # - link: Customer Showcase - # href: https://buildwithfern.com/showcase - page: MCP Server path: ./overview/mcp-server/introduction.mdx slug: mcp-server - section: Deep Dives - contents: + contents: - page: Customize Method Names path: ./guides/customize-method-names.mdx slug: customize-method-names @@ -207,7 +195,7 @@ navigation: path: ./guides/self-host-fern-generators.mdx slug: self-host-generators - section: Reference - contents: + contents: - page: generators.yml path: ./reference/generators-yml-reference.mdx slug: generators-yml From 1afcd6c525618d584c966031863ed79de4e18ffb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:28 +0000 Subject: [PATCH 3/7] Create readme.mdx based on issue #323 --- .../products/sdks/pages/deep-dives/readme.mdx | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 fern/products/sdks/pages/deep-dives/readme.mdx diff --git a/fern/products/sdks/pages/deep-dives/readme.mdx b/fern/products/sdks/pages/deep-dives/readme.mdx new file mode 100644 index 00000000..4a309447 --- /dev/null +++ b/fern/products/sdks/pages/deep-dives/readme.mdx @@ -0,0 +1,82 @@ +--- +title: "Customizing Generated READMEs" +description: "Learn how to customize the README files generated for your SDKs" +--- + +When Fern generates SDKs for your API, it automatically creates README files with installation and usage instructions. You can customize these README files to better match your documentation needs. + +## Custom README Template + +To customize the README for your generated SDKs, you can specify a custom template in your `generators.yml` file: + + +```yaml +groups: + python: + generators: + - name: fernapi/fern-python-sdk + version: 0.7.4 + output: + location: local-file-system + path: ../generated/python + config: + readme: ./custom-readme.md +``` + + +The `readme` field should point to your template file location relative to `generators.yml`. + +## Template Variables + +Your custom README template can include variables that Fern will replace when generating the file: + + + The name of the generated package + + + + Package installation instructions for the target language + + + + Code snippet showing how to initialize the client + + +## Example Template + + +```markdown +# {{package_name}} + +Official SDK for the Example API + +## Installation + +{{install_instructions}} + +## Usage + +{{initialization_instructions}} + +## Documentation + +For full documentation, visit [our docs](https://docs.example.com). + +## Support + +Contact support@example.com for assistance. +``` + + +## Reference Documentation + +For more details on configuring SDK generation options, see the [generators.yml reference](/learn/reference/configuration/generators). + + + The custom README template must be a valid Markdown file. Ensure all links and formatting are correct before generating your SDKs. + + +## Related Guides + +- [SDK Configuration Options](/learn/sdks/configuration/overview) +- [Adding Global Headers](/learn/sdks/deep-dives/global-headers) \ No newline at end of file From 6535372791f483147e0c7f16ccfdfbd010f423da Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:29 +0000 Subject: [PATCH 4/7] Add Readme page to navigation --- fern/products/sdks/sdks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 82a6e3d8..0ff4f989 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -19,7 +19,7 @@ navigation: - link: Customer Showcase href: https://buildwithfern.com/showcase - page: Readme - path: ./pages/reference/readme.mdx + path: ./pages/deep-dives/readme.mdx - section: Generators contents: - section: TypeScript From d923ad272bf25cde63f560844a9fae3155653dc4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:29 +0000 Subject: [PATCH 5/7] Update generators-yml-reference.mdx based on issue #323 --- .../reference/generators-yml-reference.mdx | 496 ++++++------------ 1 file changed, 158 insertions(+), 338 deletions(-) diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 2d1b431a..d10f3a8c 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -2,7 +2,6 @@ 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 @@ -18,6 +17,10 @@ api: title-as-schema-name: true inline-path-parameters: false respect-forward-compatible-enums: true + headers: + X-Version: + name: version + type: literal<"1234"> whitelabel: github: @@ -76,6 +79,10 @@ api: settings: title-as-schema-name: true inline-path-parameters: false + headers: + X-Version: + name: version + type: literal<"1234"> ``` ### General Configuration Options @@ -91,7 +98,9 @@ api: - asyncapi: "./events.yml" namespace: "events" headers: - Authorization: "Bearer ${API_TOKEN}" + X-Version: + name: version + type: literal<"1234"> environments: production: "https://api.prod.com" staging: "https://api.staging.com" @@ -105,8 +114,8 @@ api: Authentication configuration for the API. - - Default headers to include with API requests. + + Global headers to include with API requests. Each header can be configured with a name and type. @@ -254,20 +263,6 @@ api: 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. - - -#### Protocol Buffers - ```yaml api: specs: @@ -335,18 +330,23 @@ whitelabel: ``` + Configuration for customizing SDK branding and publishing settings. + GitHub-specific configuration for publishing SDKs. + GitHub username used for publishing. + Email associated with the GitHub account. + GitHub personal access token with required permissions. ## metadata @@ -363,22 +363,27 @@ metadata: ``` + Global metadata configuration for all SDKs in this group. + A description of your SDK that will appear in package managers. + List of authors to be included in SDK package metadata. + Name of an author. + Email of an author. ## readme -Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation. +Controls what goes into the generated README files across all SDKs. ```yaml readme: @@ -401,28 +406,28 @@ readme: path: "/users" ``` - + URL for a banner image or link that appears at the top of the README. - + Custom introduction text that appears at the beginning of the README. - + URL to your external API documentation or reference guide. - - Specifies which endpoint's code snippet to showcase as the primary example in the README. + + Specifies which endpoint's code snippet to showcase as the primary example. - - Groups endpoints by feature name for organized README sections. Each feature becomes a section in the README with example code snippets for the listed endpoints. + + Groups endpoints by feature name for organized README sections. Each feature becomes a section with example code snippets. ### defaultEndpoint -Specifies which endpoint's code snippet to showcase as the primary example in the README. +Configure which endpoint to showcase in the main example. HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`). @@ -444,10 +449,11 @@ default-group: "production" ``` + The default generator group to use when no specific group is specified. ## groups -Organizes different sets of generators (like "production" vs "staging" vs "internal") +Organizes different sets of generators (like "production" vs "staging" vs "internal"). ```yaml groups: @@ -463,53 +469,26 @@ groups: github: repository: "myorg/typescript-sdk" mode: "release" - config: - clientName: "MyApiClient" - packageName: "@myorg/api-sdk" - metadata: - package-description: "Official TypeScript SDK" - author: "MyOrg SDK Team" - keywords: ["CustomKeyword"] - snippets: - path: "./snippets" - smart-casing: true - api: - settings: - inline-path-parameters: true - - name: fernapi/fern-python-sdk - version: 2.0.0 - output: - location: pypi - package-name: "myorg-api-sdk" - token: "${PYPI_TOKEN}" - metadata: - keywords: ["api", "sdk"] - documentation-link: "https://docs.myorg.com" - metadata: - description: "Production SDKs for MyAPI" - authors: - - name: "SDK Team" - email: "sdk@myorg.com" - reviewers: - teams: - - name: "sdk-team" - users: - - name: "john-doe" ``` + Map of named generator groups and their configurations. + Configuration for a specific generator group. + List of audiences this group targets (e.g., "external", "internal"). + List of SDK generators to run for this group. + Group-specific metadata that overrides global metadata. @@ -548,6 +527,15 @@ groups: +Add global headers that will be included in all API requests. Headers can be configured either here or in your OpenAPI specification. + +```yml +api: + headers: + X-Version: + name: version + type: literal<"1234"> +``` @@ -689,7 +677,6 @@ SDK code. You can also configure a branch name, license, and reviewers. Make sure the [Fern GitHub app](https://github.com/apps/fern-api) is installed on your destination repository - #### Release (recommended) Fern generates your code, commits it to main, and tags a new release. @@ -723,130 +710,43 @@ Specify which teams and users should review generated code. See [reviewers confi #### Pull request -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. - -```yml {6-8} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - github: - repository: "your-org/your-repo-name" - mode: "pull-request" -``` - - - - - - - - - - - - - - -Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). - - -#### Push - -Fern generates your code and pushes it to the branch you specify. - ```yml {6-8} groups: ts-sdk: generators: - name: fernapi/fern-typescript-sdk ... - github: - repository: "your-org/your-repo-name" - mode: "push" - branch: "your-branch-name" # required for `mode: push` -``` - - - - - - - - - - - - - -Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). - - -### Generator Metadata - -Specify metadata for your SDK generator. + api: + headers: + X-Version: + name: "version" # codegen name of the variable + type: "literal<'1234'>" # type of the header -```yml {6-10} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - metadata: - package-description: "Description of your SDK" - email: "sdk@example.com" - reference-url: "https://docs.example.com/sdks" - license: "MIT" + auth-schemes: + bearer-token: + scheme: "bearer" + token: + name: "token" + env: "AUTH_TOKEN" ``` - -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. + + Configure global headers that will be sent with every request. Each header can specify: + - `name`: The variable name used in the generated code + - `type`: The type of the header value (e.g. string, literal, etc) - -Contact email for the package maintainer or support team. - - - -URL pointing to comprehensive documentation, API reference, or getting started guide for the SDK. - - - -Name of the individual developer, team, or organization that created and maintains the SDK. - - - -Software license for the generated SDK. + +Must be set to "bearer" for bearer token authentication. -### Snippets Configuration - -Configures snippets for a particular generator. - -```yml {6-8} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - snippets: - path: "./snippets" -``` - - -The path to the generated snippets file. + +Configuration for the bearer token. -### API Settings Override - -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. +### API URL Override -#### String Reference - -Reference a pre-defined authentication scheme by name. +Override the base URL for API requests. ```yml {6-7} groups: @@ -855,224 +755,105 @@ groups: - name: fernapi/fern-typescript-sdk ... api: - auth: "bearer-token" + url: "https://api.example.com/v1" ``` - -The name of an authentication scheme defined in your API specification. + +The base URL to use for all API requests. -#### Scheme Reference +### Namespacing -Reference a specific authentication scheme with optional documentation. +Configure how services and types are namespaced in the generated SDK. -```yml {6-9} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - api: - auth: - scheme: "my-auth-scheme" - docs: "Custom authentication method" -``` - - -The name of the authentication scheme to use. - - - -Documentation describing this authentication configuration. - - -#### Multiple Authentication Options - -Allow any of multiple authentication schemes to be used. - -```yml {6-12} +```yml {6-8} groups: ts-sdk: generators: - name: fernapi/fern-typescript-sdk ... - api: - auth: - any: - - "api-key" - - "bearer-token" - - scheme: "oauth-flow" - docs: "Supports multiple authentication methods" + namespacing: + enabled: true + package-prefix: "@example" ``` - -List of authentication schemes where any one can be used. Can include string references or scheme objects. + +Whether to enable namespacing. Defaults to true. - -Documentation describing this authentication configuration. + +A prefix to add to all package names when namespacing is enabled. -#### Custom Authentication Schemes - -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`). - - - +### Custom SDK Configuration -Send authentication tokens or API keys in custom HTTP headers. +Add custom configuration specific to individual SDK generators. -```yml {8-12} +```yml {6-9} groups: ts-sdk: generators: - name: fernapi/fern-typescript-sdk ... - api: - auth-schemes: - api-key: # User-defined name for your auth schema - header: "X-API-Key" - type: "string" - prefix: "Bearer " - env: "API_KEY" + config: + bundler: "tsc" + browser: true + outputEsm: true ``` - -The name of the header to send the authentication value in. - - - -The type of the authentication value. Defaults to "string". - - - -A prefix to add before the authentication value in the header. - - - -Environment variable name to read the authentication value from. + +Generator-specific configuration options. See the documentation for your specific generator for available options. - - +### Reviewers Configuration -Standard HTTP basic authentication using username and password credentials. +Configure which teams and users should review generated code PRs. -```yaml {8-15} +```yml {6-11} groups: ts-sdk: generators: - name: fernapi/fern-typescript-sdk ... - api: - auth-schemes: - basic-auth: # User-defined name for your auth schema - scheme: "basic" - username: - name: "username" - env: "AUTH_USERNAME" - password: - name: "password" - env: "AUTH_PASSWORD" + reviewers: + teams: + - "api-team" + - "sdk-team" + users: + - "username1" ``` - -Must be set to "basic" for basic authentication. - - -Configuration for the username field. - - - -Configuration for the password field. - - - - - -Authentication using bearer tokens in the Authorization header. - -```yml {8-12} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - api: - auth-schemes: - bearer: # User-defined name for your auth schema - scheme: "bearer" - token: - name: "token" - env: "BEARER_TOKEN" -``` - - -Must be set to "bearer" for bearer token authentication. + +GitHub team slugs that should be requested as reviewers. - -Configuration for the bearer token. + +GitHub usernames that should be requested as reviewers. - - - -OAuth 2.0 client credentials flow for machine-to-machine authentication. - -```yml {8-12} -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - ... - api: - auth-schemes: - oauth: # User-defined name for your auth schema - scheme: "oauth" - type: "client-credentials" - get-token: - endpoint: "auth.get_token" +```yaml +api: + headers: + X-Version: + name: "version" + type: 'literal<"1234">' # Example of a literal header value + Authorization: + name: "auth" + type: "string" ``` - -Must be set to "oauth" for OAuth authentication. - - - -Must be set to "client-credentials" for OAuth client credentials flow. - - - -List of OAuth scopes to request. + + Global headers to be included with all API requests. Can be configured either here or in the OpenAPI spec. - -Environment variable name for the OAuth client ID. + + The name to use for this header in the generated code. - -Environment variable name for the OAuth client secret. + + The type of the header value. Can be a basic type like "string" or a literal type like 'literal<"value">'. - -Sets the token header value prefix. Defaults to 'Bearer'. - - - -Sets the token header key name. Defaults to 'Authorization'. - - - -Configuration for the token endpoint to get access tokens. - - - -Configuration for the refresh token endpoint. - - - - ## reviewers Who should review generated code. @@ -1096,4 +877,43 @@ reviewers: Name of a GitHub team or a user. + + +## readme +Configuration for the generated README.md file. + +```yaml +readme: + title: "My API Client" + description: "A client library for the My API service" + examples: + - title: "Basic Usage" + code: | + const client = new MyApiClient(); + const response = await client.users.getUser("123"); + - title: "Authentication" + code: | + const client = new MyApiClient({ + token: "YOUR_API_TOKEN" + }); +``` + + + The title to display at the top of the README. + + + + A description of your API client library. + + + + Code examples to include in the README. + + + + The title for this example. + + + + The code snippet for this example. \ No newline at end of file From 75bbfb073803fa54bc63d4aa74efe044ce553d6d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:30 +0000 Subject: [PATCH 6/7] Create configure-global-headers.mdx based on issue #323 --- .../sdks/guides/configure-global-headers.mdx | 146 +++++++++--------- 1 file changed, 71 insertions(+), 75 deletions(-) diff --git a/fern/products/sdks/guides/configure-global-headers.mdx b/fern/products/sdks/guides/configure-global-headers.mdx index 53ec1bd1..49cab2c2 100644 --- a/fern/products/sdks/guides/configure-global-headers.mdx +++ b/fern/products/sdks/guides/configure-global-headers.mdx @@ -1,101 +1,97 @@ --- -title: Configure Global Headers -description: Guide to configuring global headers in your SDKs. +title: 'Setting Global Headers' +description: 'Learn how to add global headers to your API using Fern' --- -Your API may leverage certain headers for every endpoint or most endpoints. -These are called **global headers**. +# Setting Global Headers -## How it works for SDK users +Global headers are HTTP headers that are sent with every request to your API. There are two ways to configure global headers in Fern: -Once you configure a global header (either automatically detected or manually -specified), Fern generates an SDK that accepts this as a constructor parameter. -Users can then provide the value once, and the generated SDK automatically -includes the header in all their API calls: +1. Via the OpenAPI specification using extensions +2. Through the `generators.yml` configuration file -```python -import os +## Adding Headers in generators.yml -class Client: +You can specify global headers directly in your `generators.yml` file using the `headers` property: - def __init__(self, *, apiKey: str): +```yaml +api: + - openapi: ./path/to/openapi + headers: + X-Version: + name: version # codegen name of the variable + type: literal<"1234"> # type of the header, in this case a literal ``` -## Specifying global headers +### Header Configuration Options -Fern automatically identifies headers that are used in every request, or the -majority of requests, and marks them as global. You can manually configure additional -global headers in either `api.yml` (Fern Definition) or `openapi.yml`. +Headers can be configured with different types: - - + + The type of the header value. Supported types include: + - `literal` - A static value that doesn't change + - `string` - A dynamic string value + - `number` - A numeric value + -To specify headers that are meant to be included on every request: + + The variable name used in the generated code for this header. + - -```yaml {3} -name: api -headers: - X-App-Id: string -``` - +## Adding Headers in OpenAPI Specification -### Global path parameters -You can also specify path parameters that are meant to be included on every request: +Alternatively, you can define global headers directly in your OpenAPI specification using extensions: - ```yaml -name: api -base-path: /{userId}/{orgId} -path-parameters: - userId: string - orgId: string +openapi: 3.0.0 +info: + title: My API + version: 1.0.0 +x-fern-headers: + X-Api-Key: + name: apiKey + type: string +paths: + # ... your API paths ``` - -#### Overriding the base path +## Example Usage -If you have certain endpoints that do not live at the configured `base-path`, you can -override the `base-path` at the endpoint level. +Here's a complete example showing both approaches: -```yml imdb.yml {5} -service: - endpoints: - getMovie: - method: POST - base-path: "override/{arg}" - path: "movies/{movieId}" - path-parameters: - arg: string + +```yaml +api: + - openapi: ./openapi.yml + headers: + X-Client-Version: + name: clientVersion + type: literal<"2.0.0"> + X-Api-Key: + name: apiKey + type: string ``` + - - You cannot yet specify query parameters that are meant to be included on every request. -If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930). - - - - - -Use 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: - - header: custom_api_key - name: api_key - - header: userpool_id - optional: true + +```yaml +openapi: 3.0.0 +info: + title: My API + version: 1.0.0 +x-fern-headers: + X-Custom-Header: + name: customHeader + type: string +paths: + /users: + get: + # ... endpoint configuration ``` + -This configuration yields the following client: - -```python -import os - -class Client: + +When using both methods, headers defined in `generators.yml` take precedence over those defined in the OpenAPI specification. + - def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str]) -``` - - \ No newline at end of file +For more details on header configuration options, see our [generators.yml reference documentation](/learn/reference/generators-yml). \ No newline at end of file From 818a896a5d96de06415b02e6acf9858846327c2c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 2 Aug 2025 11:57:31 +0000 Subject: [PATCH 7/7] Add Global Headers page to navigation --- fern/products/sdks/sdks.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 0ff4f989..e41b4a94 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -18,8 +18,8 @@ navigation: slug: capabilities - link: Customer Showcase href: https://buildwithfern.com/showcase - - page: Readme - path: ./pages/deep-dives/readme.mdx + - page: Global Headers + path: ./guides/configure-global-headers.mdx - section: Generators contents: - section: TypeScript