diff --git a/fern/products/api-def/openapi/extensions/method-names.mdx b/fern/products/api-def/openapi/extensions/method-names.mdx index bc6696d786..8dca8cd40c 100644 --- a/fern/products/api-def/openapi/extensions/method-names.mdx +++ b/fern/products/api-def/openapi/extensions/method-names.mdx @@ -69,3 +69,31 @@ api: ``` `x-fern-sdk-group-name` and `x-fern-sdk-method-name` still take precedence, so you can group individual endpoints while ignoring tags elsewhere. Enabling `ignore-tags` avoids editing the spec or maintaining overlays when tags would otherwise produce awkward sub-clients, such as a `ConversationsV2Configuration` tag becoming a `conversations_v2_configuration` sub-client. + +### `x-fern-sdk-group-name` vs `x-fern-sdk-namespace` + +These two extensions serve different purposes: + +| Extension | Where it goes | What it controls | +|---|---|---| +| `x-fern-sdk-group-name` | On an individual **endpoint** (`paths`) | Which sub-client the method lives under (e.g., `client.users.create()`) | +| `x-fern-sdk-namespace` | On the **top-level spec** or in `generators.yml` | The namespace prefix for all types and methods generated from that spec, used when combining multiple APIs into one SDK | + +Use `x-fern-sdk-group-name` to organize individual endpoints into sub-clients. Use `x-fern-sdk-namespace` when you have [multiple API specs](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis) and need to keep their generated types and methods from colliding. + +### Naming schemas and response types + +`x-fern-sdk-method-name` and `x-fern-sdk-group-name` apply to **endpoints** only. To rename a **schema** (a request body type, response type, or reusable component), use [`x-fern-type-name`](/learn/api-definitions/openapi/extensions/schema-names) on the schema definition: + +```yaml title="openapi.yml" {4} +components: + schemas: + CreateUserResponse: + x-fern-type-name: UserCreatedResult + type: object + properties: + id: + type: string +``` + +This renames the generated type from `CreateUserResponse` to `UserCreatedResult` across all SDKs. diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index f9e516711a..b1bd30e4f9 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -9,6 +9,10 @@ This is the server your readers connect to, and it serves your content. To point Your MCP server is available at `your-documentation-site.com/_mcp/server`. For example, the MCP server for this site is at [https://buildwithfern.com/learn/_mcp/server](https://buildwithfern.com/learn/_mcp/server). + + The MCP server is available on every Fern plan that includes Ask Fern. Ask Fern is included on the Hobby, Team, and Enterprise plans. To check which features are included on your plan, see the [pricing page](https://buildwithfern.com/pricing). + + ## Connect to your MCP server For Claude Code and Cursor, [page action](/learn/docs/configuration/site-level-settings#page-actions-configuration) buttons let users connect in one click: diff --git a/fern/products/sdks/deep-dives/testing.mdx b/fern/products/sdks/deep-dives/testing.mdx index d442cdbf24..56cc2a0c1d 100644 --- a/fern/products/sdks/deep-dives/testing.mdx +++ b/fern/products/sdks/deep-dives/testing.mdx @@ -12,6 +12,8 @@ Fern provides comprehensive testing for your SDKs through generated and handwrit Fern auto-generates tests that must pass before SDK release. Fern generates a GitHub workflow in each SDK repository that runs unit tests and any enabled mock server tests on every pull request, commit, and release. +CI is generated automatically. When you enable generated tests, Fern writes a `.github/workflows/ci.yml` file into your SDK repository alongside the SDK code. You do not need to configure GitHub Actions yourself. If you add custom tests, include their files in `.fernignore` to prevent them from being overwritten on the next generation. + ### Unit tests Fern generates unit tests for all SDK languages. They verify individual methods in isolation without making network calls. @@ -34,6 +36,10 @@ Mock server tests are available for TypeScript, Python, Go, Java, C#, PHP, Swift | Rust | [`enableWireTests`](/learn/sdks/generators/rust/configuration#enablewiretests) | false | | Ruby | [`enableWireTests`](/learn/sdks/generators/ruby/configuration#enablewiretests) | false | + + There is no configuration option to disable JSDoc comment generation in the TypeScript SDK. Comments are always generated from your API definition's `description` fields. To reduce comment verbosity, shorten or remove `description` values in your OpenAPI spec. + + ## Integration tests diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index ffd2b1cee5..23d5a37b0b 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -7,8 +7,19 @@ max-toc-depth: 3 The `generators.yml` file serves two purposes: it declares your API definition (required for OpenAPI/AsyncAPI), and configures SDK generation, including which languages to generate, where to publish them, and how to customize each SDK. - - To enable intelligent YAML validation and autocompletion in your editor, add a schema directive to the top of your `generators.yml` file. + + Add a schema directive to the top of your `generators.yml` file to enable intelligent YAML validation and autocompletion: + + ```yaml + # yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json + ``` + + This directive is recognized by the [YAML Language Server](https://github.com/redhat-developer/yaml-language-server), which powers YAML support in **VS Code** (via the YAML extension), **IntelliJ IDEA** (via the YAML/Ansible plugin), **Neovim**, and other editors that support the language server protocol. Once active, your editor will: + - Highlight invalid field names and wrong value types in real time + - Suggest valid options as you type + - Surface required fields before you run the CLI + + Introduced in Fern CLI `0.47.3`. ```yaml title="generators.yml" maxLines=10