Skip to content

🌿 Fern Scribe: document fern export command (so that anyone can e... #308

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

🌿 Fern Scribe: document fern export command (so that anyone can e... #308

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
75 changes: 52 additions & 23 deletions fern/products/fern-def/pages/export-openapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,52 @@
---
title: Export from Fern Definition to OpenAPI
description: Export your Fern Definition files to OpenAPI using Fern's OpenAPI generator.
---

To prevent lock-in to the Fern Definition format, we provide a generator that will export your Fern Def files to OpenAPI 3.1.
This lets you switch to using OpenAPI at any time, or use your API definition with OpenAPI tools.
To convert your Fern Definition to OpenAPI, use the `fern-openapi` generator.

Update your `generators.yml` file:

<CodeBlock title="generators.yml">
```yaml
- name: fernapi/fern-openapi
version: 0.0.31
config:
format: yaml # options are yaml or json
output:
location: local-file-system
path: ../openapi # relative path to output location
```
</CodeBlock>

---
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not super familiar with this topic, but this seems like a good change and the right place to make it. I like how Fern Scribe kept all of the original information, but just restructured to add an additional option. And made it clear in the intro text that there are two ways to do the action!

title: Export from Fern Definition to OpenAPI
description: Export your Fern Definition files to OpenAPI using Fern's CLI or generator.
---

There are two ways to export your Fern Definition to OpenAPI:

## Using the CLI (Recommended)

The simplest way to export your Fern Definition to OpenAPI is using the `fern export` command:

<CodeBlock>
```bash
fern export --format openapi
```
</CodeBlock>

By default, this exports OpenAPI files in YAML format to the `generated/openapi` directory. You can customize the output format and location using flags:

<ParamField query="format" type="string">
The output format: `yaml` (default) or `json`
</ParamField>

<ParamField query="output" type="string">
The output directory path (default: `generated/openapi`)
</ParamField>

## Using the Generator

For more advanced configuration options, you can also use the `fern-openapi` generator. Update your `generators.yml` file:

<CodeBlock title="generators.yml">
```yaml
- name: fernapi/fern-openapi
version: 0.0.31
config:
format: yaml # options are yaml or json
output:
location: local-file-system
path: ../openapi # relative path to output location
```
</CodeBlock>

Then run:

<CodeBlock>
```bash
fern generate
```
</CodeBlock>

Both methods prevent lock-in to the Fern Definition format by allowing you to export to OpenAPI 3.1 at any time. This lets you switch to using OpenAPI or use your API definition with OpenAPI-compatible tools.