Skip to content

Commit e9c1465

Browse files
devin-ai-integration[bot]dsinghvi
devin-ai-integration[bot]
and
dsinghvi
committed
docs: Add Runnable Endpoint component documentation and changelog entry
- Add comprehensive documentation for the Runnable Endpoint component - Include usage examples, features, properties, and best practices - Add navigation entry for the new component page - Create changelog entry for 2025-10-17 documenting the enhancement This documents the work from PR fern-api/fern-platform#4151 which improved the Runnable Endpoint component with a componentized architecture, multiple examples support, environment selector, and enhanced form persistence. Co-Authored-By: Deep Singhvi <[email protected]>
1 parent 6195346 commit e9c1465

File tree

3 files changed

+153
-0
lines changed

3 files changed

+153
-0
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,9 @@ navigation:
8686
- page: Parameter Fields
8787
path: ./pages/component-library/default-components/parameter-fields.mdx
8888
icon: fa-duotone fa-list
89+
- page: Runnable Endpoint
90+
path: ./pages/component-library/default-components/runnable-endpoint.mdx
91+
icon: fa-duotone fa-play-circle
8992
- page: Steps
9093
path: ./pages/component-library/default-components/steps.mdx
9194
icon: fa-duotone fa-list-ol

‎fern/products/docs/pages/changelog/2025-10-17.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
## Enhanced Runnable Endpoint Component
2+
3+
We've improved the Runnable Endpoint component with a cleaner, more maintainable architecture and new features that make testing API endpoints even easier.
4+
5+
### What's New
6+
7+
**Componentized Architecture**: The Runnable Endpoint has been refactored into modular, reusable components for better maintainability and easier future enhancements.
8+
9+
**Multiple Examples Support**: When your endpoint has multiple pre-configured examples, a dropdown selector now appears in the header, making it easy to switch between different scenarios.
10+
11+
**Environment Selector**: If your API defines multiple environments, users can now select which environment to test against directly from the component interface.
12+
13+
**Open in API Reference**: A new button links directly to the full API reference page for the endpoint, providing quick access to detailed documentation.
14+
15+
**Improved Form Persistence**: Form state is now automatically saved to local storage, preserving your test data across page navigation and browser sessions.
16+
17+
### Component Structure
18+
19+
The refactored component includes:
20+
- `RunnableEndpointHeader`: Endpoint URL display, example selector, and navigation controls
21+
- `RunnableEndpointFormSection`: Input forms for headers, path parameters, query parameters, and body
22+
- `RunnableEndpointActions`: Clear and send request buttons
23+
- `RunnableEndpointResponseSection`: Response preview with syntax highlighting
24+
25+
To learn more about using Runnable Endpoints in your documentation, visit the [Runnable Endpoint docs](/learn/docs/building-and-customizing-your-docs/component-library/runnable-endpoint).

‎fern/products/docs/pages/component-library/default-components/runnable-endpoint.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: 'Runnable Endpoint'
3+
description: 'Test API endpoints directly from your documentation with an interactive request builder.'
4+
---
5+
6+
Runnable Endpoint is an interactive component that allows users to test API endpoints directly within your documentation. It provides a full-featured request builder with form inputs for headers, path parameters, query parameters, and request bodies, along with real-time response preview.
7+
8+
## Basic Usage
9+
10+
The Runnable Endpoint component automatically detects and loads endpoint definitions from your API specification. You can embed it in your documentation pages using the `<RunnableEndpoint>` component.
11+
12+
<Tabs>
13+
<Tab title="Example">
14+
```jsx
15+
<RunnableEndpoint endpoint="POST /api/users" />
16+
```
17+
</Tab>
18+
<Tab title="Markdown">
19+
````markdown
20+
<RunnableEndpoint endpoint="POST /api/users" />
21+
````
22+
</Tab>
23+
</Tabs>
24+
25+
## Features
26+
27+
### Interactive Form Builder
28+
29+
The component automatically generates input forms based on your endpoint definition, including:
30+
31+
- **Headers**: Add and configure request headers
32+
- **Path Parameters**: Fill in dynamic URL segments
33+
- **Query Parameters**: Add URL query string parameters
34+
- **Request Body**: Edit JSON request payloads
35+
36+
All fields are collapsible for a cleaner interface when working with endpoints that have many parameters.
37+
38+
### Multiple Examples Support
39+
40+
When your endpoint has multiple pre-configured examples, the Runnable Endpoint component displays a dropdown selector in the header, allowing users to quickly switch between different example scenarios.
41+
42+
<Frame>
43+
![Runnable endpoint with example selector](runnable-endpoint-examples.png)
44+
</Frame>
45+
46+
### Environment Selection
47+
48+
If your API defines multiple environments (production, staging, development), the component automatically displays an environment selector, making it easy for users to test against different base URLs.
49+
50+
### Request Execution
51+
52+
Users can send real HTTP requests to your API directly from the documentation. The component handles:
53+
54+
- Request construction with proper headers and authentication
55+
- Real-time request/response preview
56+
- Error handling and display
57+
- Response status codes and timing
58+
59+
### Link to API Reference
60+
61+
The component includes an "Open in API reference" button that navigates users to the full API reference page for the endpoint, providing quick access to detailed documentation.
62+
63+
### Form State Persistence
64+
65+
Form inputs are automatically persisted in the browser's local storage, so users' test data is preserved even when navigating between pages or refreshing the browser.
66+
67+
## Properties
68+
69+
<ParamField path="endpoint" type="string" required={false}>
70+
The endpoint locator in the format "METHOD /path". For example: `"POST /api/users"` or `"GET /api/users/{id}"`.
71+
</ParamField>
72+
73+
<ParamField path="example" type="string" required={false}>
74+
Pre-fill the form with a specific example by name. If not specified, the first example is used by default.
75+
</ParamField>
76+
77+
<ParamField path="className" type="string" required={false}>
78+
Optional CSS class name for custom styling of the component container.
79+
</ParamField>
80+
81+
## Architecture
82+
83+
The Runnable Endpoint component is built with a modular architecture:
84+
85+
- **RunnableEndpointHeader**: Displays the endpoint URL, method, example selector, and navigation controls
86+
- **RunnableEndpointFormSection**: Renders input forms for different parameter types (headers, path, query, body)
87+
- **RunnableEndpointActions**: Provides action buttons for clearing the form and sending requests
88+
- **RunnableEndpointResponseSection**: Displays the API response with syntax highlighting and formatting
89+
90+
This componentized structure makes the code easier to maintain and allows for future enhancements to individual sections without affecting others.
91+
92+
## Example with Custom Configuration
93+
94+
<Tabs>
95+
<Tab title="Example">
96+
```jsx
97+
<RunnableEndpoint
98+
endpoint="POST /api/users"
99+
example="Create Admin User"
100+
className="my-custom-runnable"
101+
/>
102+
```
103+
</Tab>
104+
<Tab title="Markdown">
105+
````markdown
106+
<RunnableEndpoint
107+
endpoint="POST /api/users"
108+
example="Create Admin User"
109+
className="my-custom-runnable"
110+
/>
111+
````
112+
</Tab>
113+
</Tabs>
114+
115+
## Best Practices
116+
117+
1. **Use descriptive examples**: When defining multiple examples in your API specification, use clear, descriptive names that help users understand what each example demonstrates.
118+
119+
2. **Include authentication details**: Make sure to document any required authentication headers or tokens that users need to provide to successfully test endpoints.
120+
121+
3. **Provide meaningful example data**: Pre-populate examples with realistic data that demonstrates the full capabilities of your API.
122+
123+
4. **Test in multiple environments**: If you offer staging and production environments, make sure both are properly configured so users can safely test without affecting production data.
124+
125+
5. **Document expected responses**: While the component shows real responses, it's helpful to document what users should expect to see for successful requests.

0 commit comments

Comments
 (0)