From dfd1a94fbc68434d7b32cb95b72eca22868757d3 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 18 Mar 2026 03:05:50 +0000 Subject: [PATCH 1/4] docs: add coverage for customer FAQ topics - Clarify Git repo ownership after self-service setup - Add plan availability and spec storage guidance to OpenAPI sync page - Update Postman integration page with publish-to-Fern flow - Document no limit on RBAC roles Co-Authored-By: bot_apk --- fern/products/api-def/openapi-pages/automation.mdx | 14 ++++++++++++-- fern/products/docs/pages/authentication/rbac.mdx | 2 ++ .../pages/getting-started/self-service-setup.mdx | 4 +++- fern/products/docs/pages/integrations/overview.mdx | 4 ++-- fern/products/docs/pages/integrations/postman.mdx | 14 ++++++++++++-- 5 files changed, 31 insertions(+), 7 deletions(-) diff --git a/fern/products/api-def/openapi-pages/automation.mdx b/fern/products/api-def/openapi-pages/automation.mdx index df1bc679a6..c581c9668c 100644 --- a/fern/products/api-def/openapi-pages/automation.mdx +++ b/fern/products/api-def/openapi-pages/automation.mdx @@ -5,7 +5,7 @@ subtitle: Pull your latest OpenAPI Specification into your Fern Folder automatic -Automatically pull your latest OpenAPI spec from a publicly available URL into your fern folder using the [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi). This keeps your committed spec in sync with your live API without manual updates. +Automatically pull your latest OpenAPI spec from a publicly available URL into your fern folder using the [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi). This keeps your committed spec in sync with your live API without manual updates. The sync-openapi action and the `fern api update` CLI command are available on all [plans](https://buildwithfern.com/pricing). ## Setup @@ -61,4 +61,14 @@ This creates daily pull requests with any API spec updates. To change the freque ## Other use cases -If your OpenAPI spec lives in a different repository (rather than at a public URL), you can sync it to your Fern folder using explicit file mappings. See the [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi) for this and other advanced configurations. +If your OpenAPI spec lives in a different repository (rather than at a public URL), you can sync it to your Fern folder using explicit file mappings. See the [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi) for this and other advanced configurations. + +## Where to store your OpenAPI spec + +Fern customers typically manage their OpenAPI specs in one of three ways: + +- **Sync from your source code repository.** Keep your OpenAPI spec in the same repo as your API source code and use the [sync-openapi GitHub Action](#setup) or the [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI command to pull updates into your Fern docs repo automatically. +- **Host at a public URL.** Serve the spec from a publicly accessible endpoint (for example, `https://api.example.com/openapi.json`) and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. +- **Commit directly into the Fern docs repo.** Check your OpenAPI spec file into the same repository that contains your `docs.yml` and Markdown pages. This is the simplest approach when you don't need to keep a separate source of truth. + +The first and third options are the most common. Hosting at a public URL is useful when you want a single canonical spec that multiple consumers can reference. diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx index 222ed1e8dc..3d2da1ac1d 100644 --- a/fern/products/docs/pages/authentication/rbac.mdx +++ b/fern/products/docs/pages/authentication/rbac.mdx @@ -26,6 +26,8 @@ roles: - admins ``` +There is no limit on the number of roles you can define. For example, you can create a separate role for each partner so that every partner only sees their own content. + Every user automatically has the `everyone` role, including unauthenticated visitors. If a user lacks the required role or isn't authenticated, Fern redirects them to your login page. ## Restricting content diff --git a/fern/products/docs/pages/getting-started/self-service-setup.mdx b/fern/products/docs/pages/getting-started/self-service-setup.mdx index b4183eead3..f293024afe 100644 --- a/fern/products/docs/pages/getting-started/self-service-setup.mdx +++ b/fern/products/docs/pages/getting-started/self-service-setup.mdx @@ -15,6 +15,8 @@ Prefer to set things up manually using the CLI? See the [Quickstart](/learn/docs When you complete the self-service workflow, Fern publishes your documentation to a brand-new site and creates a GitHub repository containing your site configuration (`docs.yml`), Markdown pages, and any API specifications. Your repo includes a `CLAUDE.md` file pre-populated with Fern documentation in [llms-full.txt format](/learn/docs/ai/llms-txt), giving AI coding assistants context for working with Fern. +After setup, you have full ownership of this repository. Push changes to your main branch to trigger an automatic rebuild and publish of your docs, or manage settings through the [Fern Dashboard](https://dashboard.buildwithfern.com). + The setup process also creates and configures: - **Organization**: An organization using your org ID, with you as a member. @@ -48,7 +50,7 @@ Enter an existing website URL (like your marketing site or blog) so Fern can aut -Fern publishes your documentation to a live URL you can visit immediately. You can also add your GitHub account as a collaborator to push changes and manage the repository, or head to the [Dashboard](/learn/dashboard/getting-started/overview) to manage your site settings. +Fern publishes your documentation to a live URL you can visit immediately. Add your GitHub account as a collaborator to take ownership of the repository. From there, you can edit files, push changes, and open pull requests just like any other Git repo. Each push to the main branch triggers the GitHub Action to rebuild and publish your docs automatically. You can also manage your site settings in the [Dashboard](/learn/dashboard/getting-started/overview). ![Site published success screen](./images/site-published.png) diff --git a/fern/products/docs/pages/integrations/overview.mdx b/fern/products/docs/pages/integrations/overview.mdx index 1764b52a7c..241052a439 100644 --- a/fern/products/docs/pages/integrations/overview.mdx +++ b/fern/products/docs/pages/integrations/overview.mdx @@ -42,7 +42,7 @@ description: Connect analytics and support tools to your Fern documentation. Set /> } @@ -95,4 +95,4 @@ are available during the workflow run. -If you want to integrate with a third-party analytics or support platforms that Fern doesn't directly support, you can do so [using custom JS](/docs/customization/custom-css-js#custom-javascript). +If you want to integrate with a third-party analytics or support platforms that Fern doesn't directly support, you can do so [using custom JS](/docs/customization/custom-css-js#custom-javascript). diff --git a/fern/products/docs/pages/integrations/postman.mdx b/fern/products/docs/pages/integrations/postman.mdx index 94f57eb52d..cf618859fd 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -1,8 +1,18 @@ --- title: Postman integration -description: Generate Postman collections from API definitions with Fern. Create example requests and responses for testing and exploring APIs. +description: Publish Postman collections as Fern docs sites, or import your OpenAPI spec into Postman directly. --- -Fern's Postman integration is no longer actively maintained. To get your API endpoints into Postman, import your OpenAPI specification directly. See [Postman's OpenAPI import docs](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/) for instructions. +## Publish Postman collections to Fern + +Postman's publish-to-Fern integration lets you generate a Fern docs site directly from a Postman collection. This integration is available on all Postman and [Fern plans](https://buildwithfern.com/pricing). + + +Postman users on the free tier must create a Postman organization before using this flow. On Fern's side, each organization can create up to 5 docs sites, of which 1 can be published on a [custom domain](/learn/docs/preview-publish/setting-up-your-domain). Additional sites or custom domains require the [Team plan](https://buildwithfern.com/pricing). + + +## Fern-to-Postman generator (deprecated) + +Fern's Postman collection generator is no longer actively maintained. To get your API endpoints into Postman, import your OpenAPI specification directly. See [Postman's OpenAPI import docs](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/) for instructions. From 5ea7ff0ce8f90b4e3711f597d31d83766e3cece7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Mar 2026 15:16:00 -0400 Subject: [PATCH 2/4] update --- fern/products/api-def/openapi-pages/automation.mdx | 11 +---------- fern/products/api-def/pages/project-structure.mdx | 8 ++++++++ fern/products/docs/pages/authentication/rbac.mdx | 2 -- fern/products/docs/pages/integrations/postman.mdx | 9 ++++----- 4 files changed, 13 insertions(+), 17 deletions(-) diff --git a/fern/products/api-def/openapi-pages/automation.mdx b/fern/products/api-def/openapi-pages/automation.mdx index c581c9668c..30299d0254 100644 --- a/fern/products/api-def/openapi-pages/automation.mdx +++ b/fern/products/api-def/openapi-pages/automation.mdx @@ -5,7 +5,7 @@ subtitle: Pull your latest OpenAPI Specification into your Fern Folder automatic -Automatically pull your latest OpenAPI spec from a publicly available URL into your fern folder using the [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi). This keeps your committed spec in sync with your live API without manual updates. The sync-openapi action and the `fern api update` CLI command are available on all [plans](https://buildwithfern.com/pricing). +Automatically pull your latest OpenAPI spec from a publicly available URL into your fern folder using the [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi). This keeps your committed spec in sync with your live API without manual updates. ## Setup @@ -63,12 +63,3 @@ This creates daily pull requests with any API spec updates. To change the freque If your OpenAPI spec lives in a different repository (rather than at a public URL), you can sync it to your Fern folder using explicit file mappings. See the [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi) for this and other advanced configurations. -## Where to store your OpenAPI spec - -Fern customers typically manage their OpenAPI specs in one of three ways: - -- **Sync from your source code repository.** Keep your OpenAPI spec in the same repo as your API source code and use the [sync-openapi GitHub Action](#setup) or the [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI command to pull updates into your Fern docs repo automatically. -- **Host at a public URL.** Serve the spec from a publicly accessible endpoint (for example, `https://api.example.com/openapi.json`) and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. -- **Commit directly into the Fern docs repo.** Check your OpenAPI spec file into the same repository that contains your `docs.yml` and Markdown pages. This is the simplest approach when you don't need to keep a separate source of truth. - -The first and third options are the most common. Hosting at a public URL is useful when you want a single canonical spec that multiple consumers can reference. diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index ee9feda485..18bb6d1a60 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -65,6 +65,14 @@ For Fern Definition, your API configuration is split across two files: `api.yml` For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. +## Where to store your API definition + +There are three common ways to manage your API definition: + +- **Commit directly into your Fern repository (recommended).** Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don't maintain the definition elsewhere. +- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/api-definitions/openapi/automation). +- **Host at a public URL.** Serve the definition from a publicly accessible endpoint and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference. + ## Multiple APIs Fern supports two approaches for working with multiple API definitions. Both require an `apis` folder — this folder must use that exact name. diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx index 3d2da1ac1d..222ed1e8dc 100644 --- a/fern/products/docs/pages/authentication/rbac.mdx +++ b/fern/products/docs/pages/authentication/rbac.mdx @@ -26,8 +26,6 @@ roles: - admins ``` -There is no limit on the number of roles you can define. For example, you can create a separate role for each partner so that every partner only sees their own content. - Every user automatically has the `everyone` role, including unauthenticated visitors. If a user lacks the required role or isn't authenticated, Fern redirects them to your login page. ## Restricting content diff --git a/fern/products/docs/pages/integrations/postman.mdx b/fern/products/docs/pages/integrations/postman.mdx index cf618859fd..25081bea0f 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -1,17 +1,16 @@ --- title: Postman integration -description: Publish Postman collections as Fern docs sites, or import your OpenAPI spec into Postman directly. +description: Publish Postman collections as Fern Docs sites, or import your OpenAPI spec into Postman directly. --- ## Publish Postman collections to Fern -Postman's publish-to-Fern integration lets you generate a Fern docs site directly from a Postman collection. This integration is available on all Postman and [Fern plans](https://buildwithfern.com/pricing). +You can generate a Fern Docs site directly from your Postman collection. Fern automatically creates an API reference from your collection with request details, sample code, and an interactive API explorer. You can also add guides, tutorials, and other content alongside the reference, and customize branding such as your domain, logo, and colors. + +See [Postman's Fern integration docs](https://learning.postman.com/docs/fern/overview) for setup instructions. - -Postman users on the free tier must create a Postman organization before using this flow. On Fern's side, each organization can create up to 5 docs sites, of which 1 can be published on a [custom domain](/learn/docs/preview-publish/setting-up-your-domain). Additional sites or custom domains require the [Team plan](https://buildwithfern.com/pricing). - ## Fern-to-Postman generator (deprecated) From e3745b7cde045be250b4420d392e3d25e5a5d710 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Mar 2026 15:20:07 -0400 Subject: [PATCH 3/4] remove repetitive info --- .../docs/pages/getting-started/self-service-setup.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/fern/products/docs/pages/getting-started/self-service-setup.mdx b/fern/products/docs/pages/getting-started/self-service-setup.mdx index f293024afe..ae9c54e7d2 100644 --- a/fern/products/docs/pages/getting-started/self-service-setup.mdx +++ b/fern/products/docs/pages/getting-started/self-service-setup.mdx @@ -15,15 +15,13 @@ Prefer to set things up manually using the CLI? See the [Quickstart](/learn/docs When you complete the self-service workflow, Fern publishes your documentation to a brand-new site and creates a GitHub repository containing your site configuration (`docs.yml`), Markdown pages, and any API specifications. Your repo includes a `CLAUDE.md` file pre-populated with Fern documentation in [llms-full.txt format](/learn/docs/ai/llms-txt), giving AI coding assistants context for working with Fern. -After setup, you have full ownership of this repository. Push changes to your main branch to trigger an automatic rebuild and publish of your docs, or manage settings through the [Fern Dashboard](https://dashboard.buildwithfern.com). - The setup process also creates and configures: - **Organization**: An organization using your org ID, with you as a member. - **Fern token**: A `FERN_TOKEN` in your repository's GitHub secrets that authenticates the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) in your CI/CD workflows, scoped to your organization. - **GitHub Action**: A workflow that runs [`fern generate --docs`](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) whenever you push changes to your main branch, automatically rebuilding and publishing your documentation. -You can use the [Fern Dashboard](/learn/dashboard/getting-started/overview) to manage your GitHub repository connection, organization members, domains, and CLI version. +After setup, you have full ownership of this repository. Push changes to your main branch to trigger an automatic rebuild and publish of your docs, or manage settings through the [Fern Dashboard](https://dashboard.buildwithfern.com). ## Setup steps From 26627ebb5f24695a20f1d9ecd2f2a534fbf83eb0 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Mar 2026 15:20:56 -0400 Subject: [PATCH 4/4] fix vale --- fern/products/docs/pages/integrations/postman.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/integrations/postman.mdx b/fern/products/docs/pages/integrations/postman.mdx index 25081bea0f..afa5ac3a51 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -7,7 +7,7 @@ description: Publish Postman collections as Fern Docs sites, or import your Open ## Publish Postman collections to Fern -You can generate a Fern Docs site directly from your Postman collection. Fern automatically creates an API reference from your collection with request details, sample code, and an interactive API explorer. You can also add guides, tutorials, and other content alongside the reference, and customize branding such as your domain, logo, and colors. +You can generate a Fern Docs site directly from your Postman collection. Fern automatically creates an API reference from your collection with request details, sample code, and an interactive API Explorer. You can also add guides, tutorials, and other content alongside the reference, and customize branding such as your domain, logo, and colors. See [Postman's Fern integration docs](https://learning.postman.com/docs/fern/overview) for setup instructions.