diff --git a/fern/products/api-def/openapi-pages/automation.mdx b/fern/products/api-def/openapi-pages/automation.mdx index df1bc679a6..30299d0254 100644 --- a/fern/products/api-def/openapi-pages/automation.mdx +++ b/fern/products/api-def/openapi-pages/automation.mdx @@ -61,4 +61,5 @@ 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. + 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/getting-started/self-service-setup.mdx b/fern/products/docs/pages/getting-started/self-service-setup.mdx index b4183eead3..ae9c54e7d2 100644 --- a/fern/products/docs/pages/getting-started/self-service-setup.mdx +++ b/fern/products/docs/pages/getting-started/self-service-setup.mdx @@ -21,7 +21,7 @@ The setup process also creates and configures: - **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 @@ -48,7 +48,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..afa5ac3a51 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -1,8 +1,17 @@ --- 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 + +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. + + +## 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.