Skip to content

Commit 0ac8f0c

Browse files
devalogdevalog
authored
Reorganize Project Structure pages; add info about generating SDKs from multiple APIs (SDKs/API Definitions) (#760)
1 parent a1d6bfa commit 0ac8f0c

File tree

3 files changed

+105
-64
lines changed

3 files changed

+105
-64
lines changed

‎fern/products/api-def/pages/project-structure.mdx‎

Lines changed: 84 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ fern/
2020
└─ spec-file.yml # API definition file
2121
```
2222

23+
## Core configuration files
24+
2325
<Note>
2426
Beyond the core files, you can optionally use an overrides file to customize your API definition without modifying the original spec. See [Overrides](/api-definitions/overview/overrides) for instructions.
2527
</Note>
@@ -41,26 +43,98 @@ determinism.
4143

4244
### `generators.yml`
4345

44-
The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/project-structure) you're generating for your API.
46+
The `generators.yml` file points to your API definition and [specifies which SDKs to generate](/sdks/overview/project-structure).
4547

4648
```yaml title="generators.yml"
47-
api:
48-
specs:
49-
- openapi: spec-file.yml
49+
# Your API definition
50+
api:
51+
specs:
52+
- openapi: ./openapi-1.yml
53+
54+
# SDK generators
55+
groups:
56+
ts-sdk:
57+
generators:
58+
- name: fernapi/fern-typescript-sdk
59+
version: <Markdown src="/snippets/version-number-ts.mdx"/>
60+
github:
61+
repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
5062
```
5163
5264
### API definition file
5365
54-
For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information.
66+
For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information.
67+
68+
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.
69+
70+
<Note>To generate API reference documentation, [set the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference) in your `docs.yml` file.</Note>
71+
72+
## Multiple APIs
73+
74+
When working with multiple API definitions, you can organize them in two ways depending on your SDK generation needs.
75+
76+
<AccordionGroup>
77+
<Accordion title="Separate SDKs for each API">
78+
79+
Use this approach when each API should generate its own independent set of SDKs.
80+
81+
```bash
82+
fern/
83+
├─ fern.config.json
84+
└─ apis/
85+
├─ user-api/
86+
│ ├─ generators.yml # Configures user-api SDKs
87+
│ └─ openapi.yml
88+
└─ payments-api/
89+
├─ generators.yml # Configures payments-api SDKs
90+
└─ openapi.yml
91+
```
92+
93+
Each API must have its own `generators.yml` file:
5594

56-
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.
95+
```yaml title="apis/user-api/generators.yml"
96+
api:
97+
specs:
98+
- openapi: openapi.yml
99+
groups:
100+
ts-sdk:
101+
generators:
102+
- name: fernapi/fern-typescript-sdk
103+
github:
104+
repository: company/user-api-typescript
105+
```
106+
</Accordion>
107+
<Accordion title="Combined SDKs from multiple APIs">
57108

109+
Use this approach to merge multiple APIs into a single set of SDKs.
58110

59-
## Multiple API definitions
111+
```bash
112+
fern/
113+
├─ fern.config.json
114+
├─ generators.yml # Single config for combined SDKs
115+
├─ user-api/
116+
│ └─ openapi.yml
117+
└─ payments-api/
118+
└─ openapi.yml
119+
```
60120

61-
<Markdown src="/snippets/multiple-apis.mdx" />
121+
List all APIs in a single `generators.yml`:
62122

63-
### Docs configuration
123+
```yaml title="generators.yml"
124+
api:
125+
specs:
126+
- openapi: user-api/openapi.yml
127+
- openapi: payments-api/openapi.yml
128+
```
64129

65-
APIs in docs are specified by [setting the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference).
130+
If your APIs have overlapping schema names, add namespaces:
66131

132+
```yaml title="generators.yml"
133+
api:
134+
specs:
135+
- openapi: user-api/openapi.yml
136+
- namespace: payments
137+
openapi: payments-api/openapi.yml
138+
```
139+
</Accordion>
140+
</AccordionGroup>

‎fern/products/sdks/project-structure.mdx‎

Lines changed: 21 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,24 @@ Before generating SDKs with Fern, set up the proper GitHub repository structure
99

1010
Fern recommends a multi-repository structure containing:
1111

12-
- **Source repository**: Contains your API definitions and SDK generation configuration
13-
- **SDK repositories**: Separate repositories for each SDK (TypeScript, Python, Go, etc.)
12+
- **Source repository** with your API definitions and SDK generation configuration
13+
- **SDK repositories** for each SDK (TypeScript, Python, Go, etc.)
1414

1515
```bash
1616
├─ company-repo # Source repository
17-
│ ├─ .github.workflows # Contains publishing workflows for all SDKs
17+
│ ├─ .github/workflows/ # Publishing workflows for all SDKs
1818
│ └─ fern/
1919
│ ├─ fern.config.json # Root-level config
2020
│ ├─ generators.yml # References SDK repos
2121
│ └─ definition/
22-
├─ overrides.yml # Optional overrides file
22+
│ ├─ overrides.yml # Optional overrides file
2323
│ └─ api.yml # Your API definition
2424
├─ typescript-sdk-repo # SDK repository
25+
│ ├─ .github/workflows/ # Generated by Fern
26+
│ ├─ scripts/
27+
│ ├─ src/
28+
│ ├─ tests/
29+
│ └─ .fernignore # Files Fern shouldn't modify
2530
├─ python-sdk-repo # SDK repository
2631
└─ go-sdk-repo # SDK repository
2732
```
@@ -51,23 +56,29 @@ Every time you run a fern CLI command, the CLI downloads itself at the correct v
5156

5257
### `generators.yml`
5358

54-
The `generators.yml` file specifies which SDKs to generate and where to publish them. It acts as the bridge between your API definitions and your SDK repositories. It contains a group for each SDK generator and points to the corresponding SDK's repository:
59+
The `generators.yml` file points to your API definition and specifies which SDKs to generate.
5560

56-
```yaml
61+
```yaml title="generators.yml"
62+
# Your API definition
63+
api:
64+
specs:
65+
- openapi: ./openapi-1.yml
66+
67+
# SDK generators
5768
groups:
5869
ts-sdk:
5970
generators:
6071
- name: fernapi/fern-typescript-sdk
6172
version: <Markdown src="/snippets/version-number-ts.mdx"/>
6273
github:
63-
repository: your-organization/typescript-sdk-repo
74+
repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
6475

6576
python-sdk:
6677
generators:
6778
- name: fernapi/fern-python-sdk
6879
version: <Markdown src="/snippets/version-number-python.mdx"/>
6980
github:
70-
repository: your-organization/python-sdk-repo
81+
repository: your-organization/python-sdk-repo # Location of Python SDK
7182
```
7283
7384
<Info title="Examples">
@@ -78,34 +89,10 @@ See the [`generators.yml` reference page](/sdks/reference/generators-yml) for co
7889

7990
### API definition file
8091

81-
For information on how to structure your API definition files, see [Project structure (API Definitions)](/api-definitions/overview/project-structure).
82-
83-
### Optional: `overrides.yml` file
84-
85-
You can optionally add an `overrides.yml` file to customize your API definition without modifying the original spec file. For more information, see [Overrides](/api-definitions/overview/overrides).
86-
87-
## SDK repository structure
88-
89-
Each SDK has its own repository with the following structure:
90-
91-
```bash
92-
typescript-sdk-repo/ # Individual SDK repository
93-
├─ .github/workflows/ # Generated by Fern
94-
├─ scripts/
95-
├─ src/
96-
├─ tests/
97-
└─ .fernignore # Files Fern shouldn't modify
98-
```
99-
100-
Fern generates most of these files automatically, including preserving any custom code you've added.
92+
See [Project structure (API Definitions)](/api-definitions/overview/project-structure) for details on organizing your API definition files and working with multiple APIs.
10193

10294
## Setup instructions
10395

10496
1. **Create repositories**: Set up your source repository, plus one repository for each SDK
10597
2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories
106-
3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.
107-
108-
## Multiple API definitions
109-
110-
<Markdown src="/snippets/multiple-apis.mdx" />
111-
98+
3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.

‎fern/snippets/multiple-apis.mdx‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

0 commit comments

Comments
 (0)