Skip to content

Commit ea4e8a9

Browse files
Kapil GowruKapil Gowru
Kapil Gowru
authored and
Kapil Gowru
committed
feat: moving more docs over
1 parent eca376d commit ea4e8a9

34 files changed

+2525
-473
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,10 +87,55 @@ navigation:
8787
path: ./pages/navigation/products.mdx
8888
- page: Changelogs
8989
path: ./pages/navigation/changelogs.mdx
90-
- page: API References
91-
path: ./pages/navigation/api-references.mdx
9290
- page: Hiding Content
9391
path: ./pages/navigation/hiding-content.mdx
92+
- section: API References
93+
contents:
94+
- page: Generate API Reference
95+
icon: fa-regular fa-wand-sparkles
96+
path: ./pages/api-references/generate-api-ref.mdx
97+
slug: generate-api-ref
98+
- page: SDK Snippets
99+
icon: fa-regular fa-brackets-curly
100+
path: ./pages/api-references/sdk-snippets.mdx
101+
- page: HTTP Snippets
102+
icon: fa-regular fa-code
103+
path: ./pages/api-references/http-snippets.mdx
104+
- section: API Explorer
105+
slug: api-explorer
106+
path: ./pages/api-references/api-explorer.mdx
107+
icon: fa-regular fa-play
108+
contents:
109+
- page: Auto-populate API Keys
110+
icon: fa-regular fa-key
111+
path: ./pages/api-references/autopopulate-api-key.mdx
112+
- page: Endpoint Errors
113+
icon: fa-regular fa-triangle-exclamation
114+
path: ./pages/api-references/endpoint-errors.mdx
115+
- page: Audiences
116+
icon: fa-regular fa-user-group
117+
path: ./pages/api-references/audiences.mdx
118+
- page: Customize API Reference Layout
119+
icon: fa-regular fa-arrows-up-down-left-right
120+
path: ./pages/api-references/customize-api-ref.mdx
121+
- page: Write Markdown in API Reference
122+
icon: fa-regular fa-pencil
123+
path: ./pages/api-references/api-ref-content.mdx
124+
- page: Generate Webhook Reference
125+
icon: fa-regular fa-webhook
126+
path: ./pages/api-references/generate-webhook-ref.mdx
127+
- page: Multiple Server URLs
128+
icon: fa-regular fa-server
129+
path: ./pages/api-references/server-urls.mdx
130+
slug: server-urls
131+
- page: Generate WebSocket Reference
132+
icon: fa-regular fa-plug
133+
path: ./pages/api-references/generate-websocket-ref.mdx
134+
slug: generate-websocket-ref
135+
- page: Generate OpenRPC Reference
136+
icon: fa-regular fa-diamond
137+
path: ./pages/api
138+
slug: generate-openrpc-ref
94139
- section: SEO
95140
collapsed: true
96141
contents:

‎fern/products/docs/pages/api-references/api-explorer.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: API Explorer
3+
subtitle: Reduce "time to 200" by allowing users to make real calls to your API from right within the API Reference.
4+
---
5+
6+
<Tip>This feature is available on the Basic plan and above. [Contact us](https://buildwithfern.com/contact) to get set up.</Tip>
7+
8+
Fern's API Explorer allows users to make authenticated requests to your API without ever leaving your documentation.
9+
10+
### Auto-populate with examples
11+
Fern will automatically populate the fields of the endpoint with the values set in your API specification.
12+
13+
<div style="position: relative; padding-bottom: 50.63657407407407%; height: 0;"><iframe src="https://www.loom.com/embed/a48d921459b54dde9652c3fcc85ebc54?sid=2c0b4f4d-7e24-4fc5-a617-8d933195bfec?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
14+
15+
### Authenticated sessions
16+
Once a user sets their authentication credentials once, their credentials persist throughout their entire exploration.
17+
18+
<div style="position: relative; padding-bottom: 50.63657407407407%; height: 0;"><iframe src="https://www.loom.com/embed/7de9948ae878448094b5e92da5effd41?sid=702889b7-aa3d-4669-994e-83c196d7bc3e?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
19+
20+
<Info>
21+
Authentication credentials are only stored client-side using cookies. No sensitive user information is collected or stored.
22+
</Info>
23+
24+
### Multiple environments
25+
Allow users to test their calls in a sandbox environment or select the environment relevant to them. Users can switch between multiple environments. Once they've selected their environment, it persists throughout their entire exploration.
26+
27+
<div style="position: relative; padding-bottom: 50.63657407407407%; height: 0;"><iframe src="https://www.loom.com/embed/cb642161678e41cabcb677b900006f40?sid=5e45243c-3ba1-45cf-860b-72eee1970fc5?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
28+
29+
### WebSocket Playground
30+
31+
For APIs that support WebSocket connections, the API Explorer includes a **WebSocket**-specific Playground. The WebSocket Playground also allows users to establish a connection with the API, and send/receive messages in real-time.
32+
33+
<div style="position: relative; padding-bottom: 56.2%; height: 0;"><iframe src="https://www.loom.com/embed/be4da30404794e9983c4fe639f78d4c8?sid=73b7aeda-98fa-4531-87ed-1e5909500fe2?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

‎fern/products/docs/pages/api-references/api-ref-content.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Write Markdown content in your API Reference
3+
description: Add Markdown content to your API Reference including summary pages and content between endpoints.
4+
---
5+
6+
Fern Docs allows you to write Markdown content in your API Reference documentation. This feature is useful for providing additional context, examples, or explanations for your API endpoints. There are a few ways to accomplish this:
7+
8+
## In OpenAPI
9+
10+
If you're using OpenAPI to define your API, you can include Markdown content in your OpenAPI Specification.
11+
12+
For example, you can include a [callout](/learn/docs/content/components/callouts#note-callouts) in the `description` field of an endpoint:
13+
14+
```yaml title="api/openapi.yml"
15+
paths:
16+
/pets:
17+
get:
18+
summary: List all pets
19+
description: |
20+
Get a list of all pets in the system.
21+
22+
<Note>This endpoint requires authentication.</Note>
23+
```
24+
25+
## In Fern Definition
26+
27+
If you're using Fern's simpler API definition format, you can include Markdown content in your API definition.
28+
29+
For example, you can include a [callout](/learn/docs/content/components/callouts#note-callouts) in the `docs` field of an endpoint:
30+
31+
```yaml title="api/service.yml"
32+
service:
33+
endpoints:
34+
get:
35+
path: /pets
36+
docs: |
37+
Get a list of all pets in the system.
38+
39+
<Note>This endpoint requires authentication.</Note>
40+
```
41+
42+
## Adding a summary page
43+
44+
You can also create a Markdown page that provides an overview of your API Reference. This page can include general information about your API, such as authentication requirements, rate limits, or other important details.
45+
46+
To add a summary page, create a Markdown file in your `fern/` folder and link to it in your `docs.yml` file:
47+
48+
```yaml title="docs.yml"
49+
navigation:
50+
- api: API Reference
51+
summary: ./pages/api-summary.mdx
52+
```
53+
54+
By including the `summary` field, the `API Reference` section title will link to the `api-summary.mdx` page.
55+
56+
## Adding Markdown content between endpoints
57+
58+
In addition to adding Markdown content to individual endpoints, you can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints.
59+
60+
This feature requires you to use the `layout` field in your `docs.yml` file, which is described in the [Customize your API Reference](/learn/docs/api-references/customize-api-reference-layout) guide.
61+
62+
To add Markdown content between endpoints, create a Markdown file in your `fern/` folder and link to it in your `docs.yml` file:
63+
64+
```yaml title="docs.yml"
65+
navigation:
66+
- api: API Reference
67+
layout:
68+
- pet:
69+
- page: Pet CRUD
70+
path: ./pages/pet-crud.mdx
71+
- addPet
72+
- updatePet
73+
- deletePet
74+
- page: Pet Search
75+
path: ./pages/pet-search.mdx
76+
- findPets
77+
- findPetsByStatus
78+
- findPetsByTags
79+
- findPetsByType
80+
- findPetsByBreed
81+
```

‎fern/products/docs/pages/api-references/audiences.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Audiences
3+
subtitle: Use audiences to filter the endpoints, schemas, and properties that are displayed in your API Reference.
4+
---
5+
6+
Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public`
7+
and `beta`. You can configure audiences in both [the OpenAPI Specification](/learn/api-definition/openapi/audiences) as well as [the Fern Definition](/learn/api-definition/fern/audiences).
8+
9+
Once you've added audiences to your API Specification, you can filter to that audience by adding the `audience` property to the `api` object in your `docs.yml` navigation.
10+
11+
<CodeBlocks>
12+
```yaml title="docs.yml" {3-4}
13+
navigation:
14+
- api: API Reference
15+
audiences:
16+
- public
17+
```
18+
</CodeBlocks>
19+
20+
Here's [an example from Schematic](https://github.com/SchematicHQ/schematic-fern-config/blob/e19f5ea69a343727ed018e79127bf4fd20ad0f7b/fern/docs.yml#L128-L129) in production.

‎fern/products/docs/pages/api-references/autopopulate-api-key.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Auto-populate API keys
3+
subtitle: Make integrating with your API frictionless by adding your login flow to the API Explorer.
4+
---
5+
6+
<Tip>
7+
This feature is available on the Pro plan. [Contact us](https://buildwithfern.com/contact) to learn more.
8+
</Tip>
9+
10+
Fern can integrate with your authentication flow, allowing users to login and have their API key automatically populated with the click of a button.
11+
12+
<div style="position: relative; padding-bottom: 66.38846737481032%; height: 0;"><iframe src="https://www.loom.com/embed/790eb5849f1c4622aae09527908fdc7a?sid=d77062f8-35c3-41ab-8669-4c28b62e233b?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
13+
14+
With this feature, you can **create new users of your API** directly from within your documentation.
15+
16+
## How it works
17+
18+
To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows:
19+
20+
1. When a user clicks the "Login" button in the API Explorer, they are redirected to your authentication page.
21+
2. After successful authentication, your system must set a cookie called `fern_token` in the user's browser.
22+
3. This token should be a [JWT](https://jwt.io) encrypted with a secret key that we provide. The JWT should contain the user's API key.
23+
24+
The JWT should have a structure similar to:
25+
26+
<CodeBlocks>
27+
```json Bearer
28+
{
29+
"fern": {
30+
"playground": {
31+
"initial_state": {
32+
"auth": {
33+
"bearer_token": "eyJhbGciOiJIUzI1c"
34+
}
35+
}
36+
}
37+
}
38+
}
39+
```
40+
41+
```json Basic
42+
{
43+
"fern": {
44+
"playground": {
45+
"initial_state": {
46+
"auth": {
47+
"basic": {
48+
"username": "your_username",
49+
"password": "your_password"
50+
}
51+
}
52+
}
53+
}
54+
}
55+
}
56+
```
57+
58+
```json Custom
59+
{
60+
"fern": {
61+
"playground": {
62+
"initial_state": {
63+
"headers": {
64+
"API-Version": "2024-02-02"
65+
},
66+
"path_parameters": {
67+
"id": "1234f"
68+
},
69+
"query_parameters": {
70+
"sort": "DESCENDING"
71+
}
72+
}
73+
}
74+
}
75+
}
76+
```
77+
78+
</CodeBlocks>
79+
80+
## Setting up auto-populated API keys
81+
82+
- [ ] Reach out to Fern to get your secret key
83+
- [ ] Send Fern the URL of your authentication page (this is where users will be redirected to after clicking the "Login" button in the API Explorer)
84+
- [ ] Add logic to your service to set the `fern_token` cookie when a user logs in
85+
86+
<Tip>For an example of how to set up the `fern_token` cookie, see our demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts).</Tip>
87+

‎fern/products/docs/pages/api-references/content-ordered.png‎

580 KB
Loading

‎fern/products/docs/pages/api-references/custom-endpoint.png‎

166 KB
Loading

‎fern/products/docs/pages/api-references/custom-section.png‎

713 KB
Loading

0 commit comments

Comments
 (0)