Skip to content

(cli, api definitions) Document fern api update, make small adjustments to OpenAPI automation page #879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 18, 2025
Merged

(cli, api definitions) Document fern api update, make small adjustments to OpenAPI automation page #879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions fern/products/api-def/openapi-pages/automation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y
## Setup
<Steps>
<Step title="Configure the origin URL">
Add the origin field to your generators.yml to specify where your OpenAPI spec is hosted:
Add the `origin` field to your `generators.yml` to specify where your OpenAPI spec is hosted:

```yml title="generators.yml"
api:
specs:
Expand All @@ -18,8 +19,9 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y
```
</Step>
<Step title="Add the GitHub Action">
Create `.github/workflows/sync-openapi.yml` in your repository:
```yml
Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file.

```yml title=".github/workflows/sync-openapi.yml"
name: Sync OpenAPI Specs # can be customized
on: # additional custom triggers can be configured
workflow_dispatch: # Manual trigger
Expand Down Expand Up @@ -57,4 +59,4 @@ 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 cross-repository sync. 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.
21 changes: 21 additions & 0 deletions fern/products/cli-api-reference/pages/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ hideOnThisPage: true
| [`fern login`](#fern-login) | Login to Fern CLI via GitHub or Google |
| [`fern logout`](#fern-logout) | Log out of the Fern CLI |
| [`fern export`](#fern-export) | Export an OpenAPI spec for your API |
| [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec |

## Documentation Commands

Expand Down Expand Up @@ -566,4 +567,24 @@ hideOnThisPage: true
Use `--include-major` to include major version upgrades. Major versions are skipped by default to prevent breaking changes.

</Accordion>
<Accordion title="fern api update">
Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and
updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/api-definitions/openapi/sync-your-open-api-specification).

<CodeBlock title="terminal">
```bash
fern api update [--api <api>]
```
</CodeBlock>

### api

Use `--api` to specify the API to update if there are multiple specs with a defined `origin` in `generators.yml`. If you don't specify an API, all OpenAPI specs with an `origin` will be updated.

<CodeBlock title="terminal">
```bash
fern api update --api public-api
```
</CodeBlock>
</Accordion>
</AccordionGroup>
2 changes: 1 addition & 1 deletion fern/products/sdks/reference/generators-yml-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ api:
</ParamField>

<ParamField path="origin" type="string" toc={true}>
URL of the API definition origin for polling updates.
URL of the API definition origin for pulling updates.
</ParamField>

<ParamField path="overrides" type="string" toc={true}>
Expand Down
2 changes: 1 addition & 1 deletion fern/snippets/openapi-specs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ api:
</ParamField>

<ParamField path="origin" type="string" toc={true}>
URL of the API definition origin for polling updates.
URL of the API definition origin for pulling updates. For instructions on how to set up automatic syncing, refer to [Sync your OpenAPI specification](/learn/api-definitions/openapi/sync-your-open-api-specification).
</ParamField>

<ParamField path="overrides" type="string" toc={true}>
Expand Down