Skip to content

Update file structure displays to use Files component #1876

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

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

Update file structure displays to use Files component #1876

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
42 changes: 24 additions & 18 deletions fern/products/api-def/asyncapi-pages/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,11 +126,13 @@ fern/
<Step title="Add your AsyncAPI specification">
Add your AsyncAPI spec to the fern directory. You can place it in a subfolder called `asyncapi` or directly in the fern directory.

```
fern/
└─ asyncapi/
└─ asyncapi.yml
```
<Files>
<Folder name="fern" defaultOpen>
<Folder name="asyncapi" defaultOpen>
<File name="asyncapi.yml" />
</Folder>
</Folder>
</Files>
</Step>
<Step title="Create a `fern.config.json` file">
Add a `fern.config.json` file in your fern directory that lists your organization and the current version of the Fern CLI:
Expand All @@ -142,12 +144,14 @@ Add a `fern.config.json` file in your fern directory that lists your organizatio
}
```

```
fern/
├─ fern.config.json
└─ asyncapi/
└─ asyncapi.yml
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<Folder name="asyncapi" defaultOpen>
<File name="asyncapi.yml" />
</Folder>
</Folder>
</Files>
</Step>
<Step title="Create a `generators.yml` file">
Create a `generators.yml` file in your fern directory and add a reference to your AsyncAPI spec:
Expand All @@ -166,12 +170,14 @@ groups:

Your final directory structure:

```
fern/
├─ fern.config.json
├─ generators.yml
└─ asyncapi/
└─ asyncapi.yml
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="asyncapi" defaultOpen>
<File name="asyncapi.yml" />
</Folder>
</Folder>
</Files>
</Step>
</Steps>
24 changes: 13 additions & 11 deletions fern/products/api-def/ferndef-pages/api-yml/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,18 @@ description: The api.yml file contains general API configuration when using the

A `fern/` folder has a special file called `api.yml`, which includes all the API-wide configuration.

```bash {5}
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
├─ api.yml
├─ pet.yml
├─ store.yml
└─ user.yml
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="pet.yml" />
<File name="store.yml" />
<File name="user.yml" />
</Folder>
</Folder>
</Files>

## API name

Expand Down Expand Up @@ -54,4 +56,4 @@ version:
- "2.0.0"
- "latest"
```
</CodeBlock>
</CodeBlock>
26 changes: 17 additions & 9 deletions fern/products/api-def/ferndef-pages/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,22 @@ subtitle: Model auth schemes such as bearer, basic, custom headers, and oauth.

Configuring authentication schemes happens in the `api.yml` file. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials.

```bash {5}
fern/
├─ fern.config.json # root-level configuration
├─ generators.yml # generators you're using
└─ definition/
├─ api.yml # API-level configuration
└─ imdb.yml # endpoints, types, and errors
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="imdb.yml" />
</Folder>
</Folder>
</Files>

Key files:
- **fern.config.json**: Root-level configuration
- **generators.yml**: Generators you're using
- **api.yml**: API-level configuration
- **imdb.yml**: Endpoints, types, and errors

To add an authentication scheme, specify the authentication method under the `auth-schemes` section.

Expand Down Expand Up @@ -262,4 +270,4 @@ auth-schemes:
token-prefix: Fern-Bearer
get-token:
...
```
```
45 changes: 25 additions & 20 deletions fern/products/api-def/ferndef-pages/depending-on-other-apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,17 @@ $ fern register
To add a dependency on another API, you must add a `dependencies.yml` to declare which
APIs you wish to depend on.

```bash {4}
fern/
├─ fern.config.json
├─ generators.yml
├─ dependencies.yml
└─ definition/
├─ api.yml
├─ imdb.yml
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<File name="dependencies.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="imdb.yml" />
</Folder>
</Folder>
</Files>

Your `dependencies.yml` has a list of all the APIs you wish to depend:

Expand All @@ -46,17 +48,20 @@ dependencies:
Next, you need create a folder in your Fern Definition to house the dependency. Inside the folder, create a special file
`__package__.yml` which specifies the dependency and version you want to add.

```bash {8-9}
fern/
├─ fern.config.json
├─ generators.yml
├─ dependencies.yml
└─ definition/
├─ api.yml
├─ imdb.yml
└─ my-folder
└─ __package__.yml
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<File name="dependencies.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="imdb.yml" />
<Folder name="my-folder" defaultOpen>
<File name="__package__.yml" />
</Folder>
</Folder>
</Folder>
</Files>

```yaml __package__.yml
export:
Expand Down
24 changes: 16 additions & 8 deletions fern/products/api-def/ferndef-pages/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,22 @@ fern init

This will create the following folder structure in your project:

```bash
fern/
├─ fern.config.json # root-level configuration
├─ generators.yml # generators you're using
└─ definition/
├─ api.yml # API-level configuration
└─ imdb.yml # endpoints, types, and errors
```
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="imdb.yml" />
</Folder>
</Folder>
</Files>

Key files:
- **fern.config.json**: Root-level configuration
- **generators.yml**: Generators you're using
- **api.yml**: API-level configuration
- **imdb.yml**: Endpoints, types, and errors

## Definition file

Expand Down
128 changes: 68 additions & 60 deletions fern/products/api-def/ferndef-pages/packages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,21 @@ description: Fern Definition enables the reuse of API type and error names acros

Every folder in your API definition is a package.

<CodeBlock title='Example of package and nested package'>
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/ # <--- root package
├─ api.yml
├─ projects.yml
└─ roles/ # <--- nested package
└─ admin.yml
```
</CodeBlock>
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<File name="projects.yml" />
<Folder name="roles" defaultOpen>
<File name="admin.yml" />
</Folder>
</Folder>
</Folder>
</Files>

Note: The `definition` folder is the root package, and `roles` is a nested package.

The generated SDK will match the hierarchy of your API definition.

Expand Down Expand Up @@ -54,16 +57,16 @@ client.getProjects();

would have a `fern/` folder:

<CodeBlock title='fern/'>
```bash {5}
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
├─ __package__.yml
└─ roles.yml
```
</CodeBlock>
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="__package__.yml" />
<File name="roles.yml" />
</Folder>
</Folder>
</Files>

that contains the following `__package__.yml`:

Expand Down Expand Up @@ -91,20 +94,25 @@ to a new package and start making changes. If the new API version reuses
certain types or errors, that's okay because the two APIs live in different
packages.

<CodeBlock title="Versioning example">
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
├─ api.yml
└─ roles/
└─ v1/
└─ admin.yml # type names can overlap with v2/admin.yml
└─ v2/
└─ admin.yml
```
</CodeBlock>
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="api.yml" />
<Folder name="roles" defaultOpen>
<Folder name="v1">
<File name="admin.yml" />
</Folder>
<Folder name="v2">
<File name="admin.yml" />
</Folder>
</Folder>
</Folder>
</Folder>
</Files>

Note: Type names can overlap between v1/admin.yml and v2/admin.yml because they're in different packages.

## Navigation

Expand All @@ -114,34 +122,34 @@ of your documentation.

For example, let's say you have the following `fern/` folder:

<CodeBlock title='fern/'>
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
├─ projects.yml
├─ roles.yml
└─ users.yml
```
</CodeBlock>
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="projects.yml" />
<File name="roles.yml" />
<File name="users.yml" />
</Folder>
</Folder>
</Files>

Your API will be sorted alphabetically: projects, roles, then users. If you
want to control the navigation, you can add a `__package__.yml` file
and configure the order:

<CodeBlock title='fern/'>
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
├─ __package__.yml # <--- New File
├─ projects.yml
├─ roles.yml
└─ users.yml
```
</CodeBlock>
<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="generators.yml" />
<Folder name="definition" defaultOpen>
<File name="__package__.yml" />
<File name="projects.yml" />
<File name="roles.yml" />
<File name="users.yml" />
</Folder>
</Folder>
</Files>

<CodeBlock title='__package__.yml'>
```yaml
Expand All @@ -150,4 +158,4 @@ navigation:
- roles.yml
- projects.yml
```
</CodeBlock>
</CodeBlock>
Loading
Loading