Skip to content

Commit af412db

Browse files
devalogdevalog
authored
Add Python quickstart and break TS quickstart into reusable snippets (#22)
1 parent 080f9f9 commit af412db

File tree

10 files changed

+265
-193
lines changed

10 files changed

+265
-193
lines changed

‎fern/products/sdks/overview/go/configuration.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,3 @@ description: Configuration options for the Fern Go SDK.
44
---
55

66
# Go Configuration
7-
8-
Discover how to configure the Fern Go SDK for your project.

‎fern/products/sdks/overview/python/quickstart.mdx‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,65 @@ title: Python Quickstart
33
description: Get started quickly with the Fern Python SDK.
44
---
55

6-
# Python Quickstart
6+
<Markdown src="/products/sdks/snippets/demo-warning.mdx"/>
77

8-
Follow these steps to quickly get up and running with the Fern Python SDK.
8+
Generate a Python SDK by following the instructions on this page.
9+
10+
<Steps>
11+
<Markdown src="/products/sdks/snippets/install-cli.mdx"/>
12+
13+
### Initialize the Fern Folder
14+
15+
You can use either the OpenAPI definition, AsyncAPI definition, or Fern
16+
Definition to generate your SDK.
17+
18+
<AccordionGroup>
19+
<Markdown src="/products/sdks/snippets/option-1-openapi.mdx"/>
20+
21+
<Markdown src="/products/sdks/snippets/option-2-asyncapi.mdx"/>
22+
23+
<Markdown src="/products/sdks/snippets/option-3-fern-def.mdx"/>
24+
25+
</AccordionGroup>
26+
27+
<Markdown src="/products/sdks/snippets/pass-fern-check.mdx"/>
28+
29+
### Add the SDK generator
30+
31+
Add the Python SDK generator:
32+
33+
```bash
34+
fern add fern-python-sdk --group sdk
35+
```
36+
37+
This command adds the following to `generators.yml`:
38+
39+
```yaml
40+
sdk:
41+
generators:
42+
- name: fernapi/fern-python-sdk
43+
version: <Markdown src="/snippets/version-number.mdx"/>
44+
output:
45+
location: local-file-system
46+
path: ../sdks/python
47+
```
48+
49+
<Markdown src="/products/sdks/snippets/generate-sdk.mdx"/>
50+
51+
```bash
52+
fern/ # created in step 1
53+
sdks/ # created by fern generate --group sdk
54+
├─ python
55+
├─ __init__.py
56+
├─ client.py
57+
├─ core/
58+
└─ imdb/ # or the name of your API
59+
├─ errors/
60+
└─ types/
61+
```
62+
63+
<Note>Some files, including `pyproject.toml` and `README.md`, are only generated on paid plans.
64+
To get the fully generated SDK, schedule a
65+
[demo](https://buildwithfern.com/contact) or [email
66+
us](mailto:[email protected]).</Note>
67+
</Steps>

‎fern/products/sdks/overview/typescript/quickstart.mdx‎

Lines changed: 42 additions & 189 deletions
Original file line numberDiff line numberDiff line change
@@ -3,208 +3,61 @@ title: TypeScript Quickstart
33
description: Get started quickly with the Fern Typescript SDK.
44
---
55

6-
<Warning title='Schedule a Demo'>
7-
Generating SDKs often requires understanding the state of your OpenAPI Specification as well as
8-
your specific requirements. For the ideal experience, we **strongly recommend** scheduling a
9-
[demo](https://buildwithfern.com/contact) or [emailing us](mailto:[email protected]) to get started.
10-
</Warning>
6+
<Markdown src="/products/sdks/snippets/demo-warning.mdx"/>
117

128
Generate a TypeScript SDK by following the instructions on this page.
139

1410
<Steps>
15-
### Install the Fern CLI
16-
17-
Run the following command to install the CLI tool or update it to the latest version:
18-
19-
```bash
20-
npm install -g fern-api
21-
```
11+
<Markdown src="/products/sdks/snippets/install-cli.mdx"/>
2212

2313
### Initialize the Fern Folder
2414

2515
You can use either the OpenAPI definition, AsyncAPI definition, or Fern Definition to generate your SDK.
2616

2717
<AccordionGroup>
28-
<Accordion title="Option 1: OpenAPI">
29-
Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location.
30-
31-
<Tip>
32-
Fern can handle both JSON and YML formats for OpenAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in.
33-
</Tip>
34-
35-
<Info>
36-
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
37-
</Info>
38-
39-
<CodeBlocks>
40-
41-
<CodeBlock title="Local file">
42-
```bash
43-
fern init --openapi path/to/openapi.yml --organization <YourOrganization>
44-
```
45-
</CodeBlock>
46-
47-
<CodeBlock title="Web-hosted file">
48-
```bash
49-
fern init --openapi https://api.example.com/openapi.yml --organization <YourOrganization>
50-
```
51-
</CodeBlock>
52-
53-
</CodeBlocks>
54-
55-
This creates a `fern` folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files.
56-
57-
```bash
58-
fern/
59-
├─ fern.config.json # root-level configuration
60-
└─ api/ # your API
61-
├─ generators.yml # generators you're using
62-
└─ openapi/
63-
├─ openapi.yml # API-level configuration
64-
```
65-
</Accordion>
66-
<Accordion title="Option 2: AsyncAPI">
67-
Initialize the Fern folder using your AsyncAPI Specification. Run one of the following commands based on your spec's location.
68-
69-
<Tip>
70-
Fern can handle both JSON and YML formats for AsyncAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in.
71-
</Tip>
72-
73-
<Info>
74-
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
75-
</Info>
76-
77-
<CodeBlocks>
78-
79-
<CodeBlock title="Local file">
80-
```bash
81-
fern init --asyncapi path/to/asyncapi.yml --organization <YourOrganization>
82-
```
83-
</CodeBlock>
84-
85-
<CodeBlock title="Web-hosted file">
86-
```bash
87-
fern init --asyncapi https://api.example.com/asyncapi.yml --organization <YourOrganization>
88-
```
89-
</CodeBlock>
90-
91-
</CodeBlocks>
92-
93-
This creates a `fern` folder in your current directory with the AsyncAPI Specification. The exact folder structure might look different depending on your initial input files.
94-
95-
```bash
96-
fern/
97-
├─ fern.config.json # root-level configuration
98-
└─ api/ # your API
99-
├─ generators.yml # generators you're using
100-
└─ openapi/
101-
├─ openapi.yml # API-level configuration
102-
```
103-
</Accordion>
104-
<Accordion title="Option 3: Fern Definition">
105-
106-
1. Initialize the Fern folder using the Fern Definition by running the following command:
107-
108-
```bash
109-
fern init --organization <YourOrganization>
110-
```
111-
112-
<Info>
113-
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
114-
</Info>
115-
116-
This creates a `fern` folder in your current directory with the Fern Definition.
117-
118-
```bash
119-
fern/
120-
├─ fern.config.json # root-level configuration
121-
├─ generators.yml # generators you're using
122-
└─ definition/
123-
├─ api.yml # API-level configuration
124-
└─ imdb.yml # endpoints, types, and errors
125-
```
126-
127-
<Note>
128-
`imdb.yml` contains an example movies API. If you’re just generating an SDK for test purposes, you can leave this file as it is. To generate an SDK for your own API instead of the example movies API, replace `imdb.yml` with your own endpoints, types, and errors before proceeding with the rest of this page.
129-
</Note>
130-
131-
{/* TODO: show want generators.yml looks like, link out to configuration.md */}
132-
133-
1. Add the config option `outputSourceFiles: true` to `generators.yml`. This ensures your SDK contains `.ts` files instead of compiled output.
134-
135-
```yaml {11-12}
136-
# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json
137-
default-group: local
138-
groups:
139-
local:
140-
generators:
141-
- name: fernapi/fern-typescript-node-sdk
142-
output:
143-
location: local-file-system
144-
path: ../sdks/typescript
145-
version: <Markdown src="/snippets/version-number.mdx"/>
146-
config:
147-
outputSourceFiles: true
148-
```
149-
150-
18+
<Markdown src="/products/sdks/snippets/option-1-openapi.mdx"/>
15119

20+
<Markdown src="/products/sdks/snippets/option-2-asyncapi.mdx"/>
21+
22+
<Markdown src="/products/sdks/snippets/option-3-fern-def.mdx"/>
15223

153-
</Accordion>
15424
</AccordionGroup>
15525

156-
### Pass `fern check`
157-
158-
Run `fern check` to ensure that your API Definition is valid. If there are any errors,
159-
fix them before proceeding.
160-
161-
<Note>
162-
If you're using an OpenAPI Specification, check out all of our
163-
[supported extensions](/learn/api-definition/openapi/extensions).
164-
</Note>
165-
166-
### Add the SDK generator
167-
168-
Add the TypeScript SDK generator:
169-
170-
```bash
171-
fern add fern-typescript-node-sdk --group sdk
172-
```
173-
174-
This command adds the following to `generators.yml`:
175-
176-
```yaml
177-
sdk:
178-
generators:
179-
- name: fernapi/fern-typescript-node-sdk
180-
version: <Markdown src="/snippets/version-number.mdx"/>
181-
output:
182-
location: local-file-system
183-
path: ../sdks/typescript
184-
```
185-
### Generate the SDK
186-
187-
Generate the SDK:
188-
189-
```bash
190-
fern generate --group sdk
191-
```
192-
193-
This creates a `sdks` folder in your current directory. The resulting folder structure looks like this:
194-
195-
196-
```bash
197-
fern/ # created in step 1
198-
sdks/ # created by fern generate --group sdk
199-
├─ typescript
200-
├─ cjs/
201-
├─ api/
202-
├─ core/
203-
└─ errors/
204-
└─ esm/
205-
├─ api/
206-
├─ core/
207-
└─ errors/
208-
```
26+
<Markdown src="/products/sdks/snippets/pass-fern-check.mdx"/>
27+
28+
### Add the SDK generator
29+
30+
Add the TypeScript SDK generator:
31+
32+
```bash
33+
fern add fern-typescript-node-sdk --group sdk
34+
```
35+
36+
This command adds the following to `generators.yml`:
37+
38+
```yaml
39+
sdk:
40+
generators:
41+
- name: fernapi/fern-typescript-node-sdk
42+
version: <Markdown src="/snippets/version-number.mdx"/>
43+
output:
44+
location: local-file-system
45+
path: ../sdks/typescript
46+
```
47+
<Markdown src="/products/sdks/snippets/generate-sdk.mdx"/>
48+
49+
```bash
50+
fern/ # created in step 1
51+
sdks/ # created by fern generate --group sdk
52+
├─ typescript
53+
├─ cjs/
54+
├─ api/
55+
├─ core/
56+
└─ errors/
57+
└─ esm/
58+
├─ api/
59+
├─ core/
60+
└─ errors/
61+
```
20962

21063
</Steps>

‎fern/products/sdks/snippets/demo-warning.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<Warning title='Schedule a Demo'>
2+
Generating SDKs often requires understanding the state of your OpenAPI Specification as well as
3+
your specific requirements. For the ideal experience, we **strongly recommend** scheduling a
4+
[demo](https://buildwithfern.com/contact) or [emailing us](mailto:[email protected]) to get started.
5+
</Warning>

‎fern/products/sdks/snippets/generate-sdk.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
### Generate the SDK
2+
3+
Generate the SDK:
4+
5+
```bash
6+
fern generate --group sdk
7+
```
8+
9+
This creates a `sdks` folder in your current directory. The resulting folder structure looks like this:

‎fern/products/sdks/snippets/install-cli.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Install the Fern CLI
2+
3+
Run the following command to install the CLI tool or update it to the latest version:
4+
5+
```bash
6+
npm install -g fern-api
7+
```

‎fern/products/sdks/snippets/option-1-openapi.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<Accordion title="Option 1: OpenAPI">
2+
Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location.
3+
4+
<Tip>
5+
Fern can handle both JSON and YML formats for OpenAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in.
6+
</Tip>
7+
8+
<Info>
9+
`--organization <YourOrganization>` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK.
10+
</Info>
11+
12+
<CodeBlocks>
13+
14+
<CodeBlock title="Local file">
15+
```bash
16+
fern init --openapi path/to/openapi.yml --organization <YourOrganization>
17+
```
18+
</CodeBlock>
19+
20+
<CodeBlock title="Web-hosted file">
21+
```bash
22+
fern init --openapi https://api.example.com/openapi.yml --organization <YourOrganization>
23+
```
24+
</CodeBlock>
25+
26+
</CodeBlocks>
27+
28+
This creates a `fern` folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files.
29+
30+
```bash
31+
fern/
32+
├─ fern.config.json # root-level configuration
33+
└─ api/ # your API
34+
├─ generators.yml # generators you're using
35+
└─ openapi/
36+
├─ openapi.yml # API-level configuration
37+
```
38+
</Accordion>

0 commit comments

Comments
 (0)