Skip to content

Commit ee0875a

Browse files
devalogdevalog
authored
When a page has options for both OpenAPI and Fern Definition, put OpenAPI option first (#333)
1 parent 0cc3f6e commit ee0875a

File tree

3 files changed

+163
-163
lines changed

3 files changed

+163
-163
lines changed

‎fern/products/sdks/guides/configure-global-headers.mdx‎

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -28,53 +28,6 @@ majority of requests, and marks them as global. You can manually configure addit
2828
global headers in either `api.yml` (Fern Definition) or `openapi.yml`.
2929

3030
<AccordionGroup>
31-
<Accordion title="Fern Definition">
32-
33-
To specify headers that are meant to be included on every request:
34-
35-
<CodeBlock title="api.yml">
36-
```yaml {3}
37-
name: api
38-
headers:
39-
X-App-Id: string
40-
```
41-
</CodeBlock>
42-
43-
### Global path parameters
44-
You can also specify path parameters that are meant to be included on every request:
45-
46-
<CodeBlock title="api.yml">
47-
```yaml
48-
name: api
49-
base-path: /{userId}/{orgId}
50-
path-parameters:
51-
userId: string
52-
orgId: string
53-
```
54-
</CodeBlock>
55-
56-
#### Overriding the base path
57-
58-
If you have certain endpoints that do not live at the configured `base-path`, you can
59-
override the `base-path` at the endpoint level.
60-
61-
```yml imdb.yml {5}
62-
service:
63-
endpoints:
64-
getMovie:
65-
method: POST
66-
base-path: "override/{arg}"
67-
path: "movies/{movieId}"
68-
path-parameters:
69-
arg: string
70-
```
71-
72-
<Note>
73-
You cannot yet specify query parameters that are meant to be included on every request.
74-
If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).
75-
</Note>
76-
77-
</Accordion>
7831
<Accordion title="OpenAPI">
7932

8033
For OpenAPI specifications, you can configure global headers in two ways:
@@ -123,5 +76,52 @@ class Client:
12376
```
12477

12578

79+
</Accordion>
80+
<Accordion title="Fern Definition">
81+
82+
To specify headers that are meant to be included on every request:
83+
84+
<CodeBlock title="api.yml">
85+
```yaml {3}
86+
name: api
87+
headers:
88+
X-App-Id: string
89+
```
90+
</CodeBlock>
91+
92+
### Global path parameters
93+
You can also specify path parameters that are meant to be included on every request:
94+
95+
<CodeBlock title="api.yml">
96+
```yaml
97+
name: api
98+
base-path: /{userId}/{orgId}
99+
path-parameters:
100+
userId: string
101+
orgId: string
102+
```
103+
</CodeBlock>
104+
105+
#### Overriding the base path
106+
107+
If you have certain endpoints that do not live at the configured `base-path`, you can
108+
override the `base-path` at the endpoint level.
109+
110+
```yml imdb.yml {5}
111+
service:
112+
endpoints:
113+
getMovie:
114+
method: POST
115+
base-path: "override/{arg}"
116+
path: "movies/{movieId}"
117+
path-parameters:
118+
arg: string
119+
```
120+
121+
<Note>
122+
You cannot yet specify query parameters that are meant to be included on every request.
123+
If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).
124+
</Note>
125+
126126
</Accordion>
127127
</AccordionGroup>

‎fern/products/sdks/guides/customize-method-names.mdx‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -82,22 +82,6 @@ For OpenAPI, use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extens
8282
explicitly define your method name and grouping.
8383

8484
<AccordionGroup>
85-
<Accordion title="Fern Definition">
86-
87-
In the example below, Fern will generate a method called `client.users.create()`:
88-
89-
```yaml title="users.yml" {4, 6}
90-
services:
91-
http:
92-
UsersService:
93-
base-path: /users # This defines the group/namespace for the methods
94-
endpoints:
95-
create: # This defines the specific method name within the group
96-
method: POST
97-
path: ""
98-
```
99-
100-
</Accordion>
10185
<Accordion title="OpenAPI">
10286

10387
In the example below, Fern will generate a
@@ -150,6 +134,22 @@ paths:
150134
- notifications
151135
x-fern-sdk-method-name: send
152136
```
137+
</Accordion>
138+
<Accordion title="Fern Definition">
139+
140+
In the example below, Fern will generate a method called `client.users.create()`:
141+
142+
```yaml title="users.yml" {4, 6}
143+
services:
144+
http:
145+
UsersService:
146+
base-path: /users # This defines the group/namespace for the methods
147+
endpoints:
148+
create: # This defines the specific method name within the group
149+
method: POST
150+
path: ""
151+
```
152+
153153
</Accordion>
154154
</AccordionGroup>
155155

‎fern/products/sdks/guides/filter-your-endpoints-audiences.mdx‎

Lines changed: 100 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -22,106 +22,6 @@ be included in your SDK regardless of their audience tags.
2222

2323

2424
<AccordionGroup>
25-
<Accordion title="Fern Definition">
26-
27-
Configuring audiences in a Fern Definition involves:
28-
29-
1. Explicitly defining audiences in `api.yml`.
30-
1. Configuring audiences for specific endpoints, types, and properties.
31-
1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
32-
33-
<Steps>
34-
### Defining audiences
35-
36-
Audiences are explicitly declared in Fern Definition.
37-
To use audiences in your Fern Definition, add them to `api.yml`.
38-
39-
In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:
40-
41-
```yaml title='api.yml' {2-5}
42-
name: api
43-
audiences:
44-
- internal
45-
- beta
46-
- customers
47-
```
48-
### Apply audiences to your endpoints, types, and properties
49-
50-
Once you've defined audiences, mark endpoints, types, or properties for a
51-
particular consumer by adding an `audience` with the relevant groups.
52-
53-
<AccordionGroup>
54-
<Accordion title="Endpoints">
55-
56-
In this example, the `sendEmail` endpoint is only available to internal consumers:
57-
58-
```yaml title='user.yml' {6-7}
59-
service:
60-
base-path: /users
61-
auth: true
62-
endpoints:
63-
sendEmail:
64-
audiences:
65-
- internal
66-
path: /send-email
67-
...
68-
```
69-
</Accordion>
70-
<Accordion title="Types">
71-
72-
Types can also be marked for different audiences.
73-
74-
In this example, the `Email` type is available to internal and beta consumers:
75-
76-
```yaml title='user.yml' {5-7}
77-
Email:
78-
properties:
79-
subject: string
80-
body: optional<string>
81-
audiences:
82-
- internal
83-
- beta
84-
```
85-
</Accordion>
86-
<Accordion title="Properties">
87-
In this example, the `to` property is available to beta consumers only:
88-
89-
```yaml title='user.yml' {8-9}
90-
Email:
91-
properties:
92-
subject: string
93-
body: optional<string>
94-
to:
95-
type: string
96-
docs: The recipient of the email
97-
audiences:
98-
- beta
99-
```
100-
</Accordion>
101-
</AccordionGroup>
102-
103-
### Set up SDK filters in `generators.yml`
104-
105-
In `generators.yml`, you can apply audience filters so that only certain
106-
endpoints are passed to the generators.
107-
108-
The following example configures the SDKs to filter for `customers`:
109-
110-
```yaml title='generators.yml' {3-4}
111-
groups:
112-
external:
113-
audiences:
114-
- customers
115-
generators:
116-
...
117-
```
118-
### Generate your SDK
119-
120-
```bash
121-
fern generate --group sdk
122-
```
123-
</Steps>
124-
</Accordion>
12525
<Accordion title="OpenAPI">
12626

12727
Configuring audiences in an OpenAPI spec involves:
@@ -236,4 +136,104 @@ groups:
236136

237137
</Steps>
238138
</Accordion>
139+
<Accordion title="Fern Definition">
140+
141+
Configuring audiences in a Fern Definition involves:
142+
143+
1. Explicitly defining audiences in `api.yml`.
144+
1. Configuring audiences for specific endpoints, types, and properties.
145+
1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
146+
147+
<Steps>
148+
### Defining audiences
149+
150+
Audiences are explicitly declared in Fern Definition.
151+
To use audiences in your Fern Definition, add them to `api.yml`.
152+
153+
In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:
154+
155+
```yaml title='api.yml' {2-5}
156+
name: api
157+
audiences:
158+
- internal
159+
- beta
160+
- customers
161+
```
162+
### Apply audiences to your endpoints, types, and properties
163+
164+
Once you've defined audiences, mark endpoints, types, or properties for a
165+
particular consumer by adding an `audience` with the relevant groups.
166+
167+
<AccordionGroup>
168+
<Accordion title="Endpoints">
169+
170+
In this example, the `sendEmail` endpoint is only available to internal consumers:
171+
172+
```yaml title='user.yml' {6-7}
173+
service:
174+
base-path: /users
175+
auth: true
176+
endpoints:
177+
sendEmail:
178+
audiences:
179+
- internal
180+
path: /send-email
181+
...
182+
```
183+
</Accordion>
184+
<Accordion title="Types">
185+
186+
Types can also be marked for different audiences.
187+
188+
In this example, the `Email` type is available to internal and beta consumers:
189+
190+
```yaml title='user.yml' {5-7}
191+
Email:
192+
properties:
193+
subject: string
194+
body: optional<string>
195+
audiences:
196+
- internal
197+
- beta
198+
```
199+
</Accordion>
200+
<Accordion title="Properties">
201+
In this example, the `to` property is available to beta consumers only:
202+
203+
```yaml title='user.yml' {8-9}
204+
Email:
205+
properties:
206+
subject: string
207+
body: optional<string>
208+
to:
209+
type: string
210+
docs: The recipient of the email
211+
audiences:
212+
- beta
213+
```
214+
</Accordion>
215+
</AccordionGroup>
216+
217+
### Set up SDK filters in `generators.yml`
218+
219+
In `generators.yml`, you can apply audience filters so that only certain
220+
endpoints are passed to the generators.
221+
222+
The following example configures the SDKs to filter for `customers`:
223+
224+
```yaml title='generators.yml' {3-4}
225+
groups:
226+
external:
227+
audiences:
228+
- customers
229+
generators:
230+
...
231+
```
232+
### Generate your SDK
233+
234+
```bash
235+
fern generate --group sdk
236+
```
237+
</Steps>
238+
</Accordion>
239239
</AccordionGroup>

0 commit comments

Comments
 (0)