diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 2b01acf9f..32804d603 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -27,3 +27,8 @@ exceptions: - Support - Markdown - Docs + - GitHub + - Actions + - CI/CD + - CircleCI + - GitLab diff --git a/fern/docs.yml b/fern/docs.yml index 1bd6e2298..a4f932c58 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -8,7 +8,7 @@ instances: repo: docs branch: main -title: Fern Documentation +title: Fern documentation metadata: og:image: https://fern-docs.s3.us-east-2.amazonaws.com/fern-docs-og_image-compressed.png @@ -43,14 +43,14 @@ products: slug: ask-fern subtitle: Let users find answers in your documentation instantly - - display-name: CLI Reference + - display-name: CLI reference subtitle: Manage and configure your Fern projects path: ./products/cli-api-reference/cli-api-reference.yml icon: fa-regular fa-terminal image: ./images/product-switcher/product-switcher-cliapi-light.png slug: cli-api-reference - - display-name: API Definitions + - display-name: API definitions path: ./products/api-def/api-def.yml icon: fa-regular fa-book image: ./images/product-switcher/openapi-definition-light.png diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 1e579e6c9..7322d283b 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -31,7 +31,7 @@ navigation: - page: Multipart form uploads path: ./openapi-pages/endpoints/multipart.mdx slug: multipart - - page: Server-sent events + - page: Server-Sent Events path: ./openapi-pages/endpoints/sse.mdx slug: sse - section: Extensions @@ -145,7 +145,7 @@ navigation: - section: Methods slug: methods contents: - - page: JSON-RPC methods + - page: Json-rpc methods path: ./openrpc-pages/methods/rpc-methods.mdx slug: rpc-methods - page: Notifications @@ -238,7 +238,7 @@ navigation: - page: Bytes path: ./ferndef-pages/endpoints/bytes.mdx slug: bytes - - page: Server-sent events + - page: Server-Sent Events path: ./ferndef-pages/endpoints/sse.mdx slug: sse - section: Advanced @@ -259,7 +259,7 @@ navigation: path: ./ferndef-pages/audiences.mdx - page: Availability path: ./ferndef-pages/availability.mdx - - section: api.yml reference + - section: Api.yml reference slug: api-yml contents: - page: Overview diff --git a/fern/products/api-def/asyncapi-def.yml b/fern/products/api-def/asyncapi-def.yml index 5ecf82814..7accd8373 100644 --- a/fern/products/api-def/asyncapi-def.yml +++ b/fern/products/api-def/asyncapi-def.yml @@ -1,5 +1,5 @@ navigation: - - page: AsyncAPI Definition Redirect Page + - page: AsyncAPI definition redirect page path: ./pages/asyncapi-empty.mdx slug: empty-page hidden: true diff --git a/fern/products/api-def/asyncapi-pages/auth.mdx b/fern/products/api-def/asyncapi-pages/auth.mdx index 8083f6001..f46c3aff1 100644 --- a/fern/products/api-def/asyncapi-pages/auth.mdx +++ b/fern/products/api-def/asyncapi-pages/auth.mdx @@ -59,7 +59,7 @@ components: env: AUTH_TOKEN ``` -## API Key security scheme +## API key security scheme Start by defining an `apiKey` security scheme in your `asyncapi.yml`: @@ -81,7 +81,7 @@ const client = new Client({ }) ``` -### Custom API Key variable name +### Custom API key variable name If you want to control variable naming and the environment variable to scan, use the configuration below: @@ -120,7 +120,7 @@ const client = new Client({ }) ``` -### Custom Basic Auth variable names +### Custom basic auth variable names If you want to control variable naming and the environment variables to scan, use the configuration below: @@ -139,7 +139,7 @@ components: env: PASSWORD ``` -## OAuth2 security scheme +## Oauth2 security scheme diff --git a/fern/products/api-def/asyncapi-pages/automation.mdx b/fern/products/api-def/asyncapi-pages/automation.mdx index ffeb260cb..6f0793aba 100644 --- a/fern/products/api-def/asyncapi-pages/automation.mdx +++ b/fern/products/api-def/asyncapi-pages/automation.mdx @@ -85,7 +85,7 @@ api: version: 0.8.8 ``` -### From Git repository +### From git repository ```yaml title="generators.yml" {3-7} api: specs: @@ -200,4 +200,4 @@ api: version: 0.8.8 ``` -This ensures that any breaking changes to your AsyncAPI specification are detected and the appropriate team members are notified before the changes are propagated to your SDKs and documentation. \ No newline at end of file +This ensures that any breaking changes to your AsyncAPI specification are detected and the appropriate team members are notified before the changes are propagated to your SDKs and documentation. \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/channels/bindings.mdx b/fern/products/api-def/asyncapi-pages/channels/bindings.mdx index aac3ae4e2..7b6b97246 100644 --- a/fern/products/api-def/asyncapi-pages/channels/bindings.mdx +++ b/fern/products/api-def/asyncapi-pages/channels/bindings.mdx @@ -58,7 +58,7 @@ operations: method: message ``` -## MQTT bindings +## Mqtt bindings Configure MQTT-specific settings for IoT and messaging applications: diff --git a/fern/products/api-def/asyncapi-pages/overview.mdx b/fern/products/api-def/asyncapi-pages/overview.mdx index 4b4ebbbd8..9e1123ad3 100644 --- a/fern/products/api-def/asyncapi-pages/overview.mdx +++ b/fern/products/api-def/asyncapi-pages/overview.mdx @@ -109,7 +109,7 @@ components: - message ``` -## Set up your fern folder +## Set up your Fern folder Considering options to generate an AsyncAPI spec? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) diff --git a/fern/products/api-def/ferndef-def.yml b/fern/products/api-def/ferndef-def.yml index b69e2330e..f67229369 100644 --- a/fern/products/api-def/ferndef-def.yml +++ b/fern/products/api-def/ferndef-def.yml @@ -1,5 +1,5 @@ navigation: - - page: Fern Definition Redirect Page + - page: Fern Definition redirect page path: ./pages/ferndef-empty.mdx slug: empty-page hidden: true diff --git a/fern/products/api-def/ferndef-pages/audiences.mdx b/fern/products/api-def/ferndef-pages/audiences.mdx index 06846941c..6f67478ad 100644 --- a/fern/products/api-def/ferndef-pages/audiences.mdx +++ b/fern/products/api-def/ferndef-pages/audiences.mdx @@ -99,7 +99,7 @@ groups: ... ``` -## Audiences with docs +## Audiences with docs If generating Fern Docs, update your `docs.yml` configuration to include your audiences. diff --git a/fern/products/api-def/ferndef-pages/availability.mdx b/fern/products/api-def/ferndef-pages/availability.mdx index bc11fde27..bdd5ed9b9 100644 --- a/fern/products/api-def/ferndef-pages/availability.mdx +++ b/fern/products/api-def/ferndef-pages/availability.mdx @@ -13,7 +13,7 @@ Availability can be: - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag - `generally-available` which means it is stable and available for use; will show a `GA` tag -### Endpoint +### Endpoint ```yaml {6} @@ -71,7 +71,7 @@ In Fern Docs, this will look like: ![Screenshot showing a beta tag next to a type in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/type-beta.png) -### Property +### Property ```yaml {12} diff --git a/fern/products/api-def/ferndef-pages/endpoints.mdx b/fern/products/api-def/ferndef-pages/endpoints.mdx index 2fba4152a..79d92029c 100644 --- a/fern/products/api-def/ferndef-pages/endpoints.mdx +++ b/fern/products/api-def/ferndef-pages/endpoints.mdx @@ -283,7 +283,7 @@ types: ``` -### Response status codes +### Response status codes You can also use the `status-code` field to specify a custom status code for a success response. diff --git a/fern/products/api-def/ferndef-pages/endpoints/multipart.mdx b/fern/products/api-def/ferndef-pages/endpoints/multipart.mdx index f5270d6ca..6add4023b 100644 --- a/fern/products/api-def/ferndef-pages/endpoints/multipart.mdx +++ b/fern/products/api-def/ferndef-pages/endpoints/multipart.mdx @@ -24,7 +24,7 @@ service: Within a given multipart request, a string parameter with `format:binary` will represent an arbitrary file. -## List of Files +## List of files If your endpoint supports a list of files, then your request body must indicate such. diff --git a/fern/products/api-def/ferndef-pages/endpoints/sse.mdx b/fern/products/api-def/ferndef-pages/endpoints/sse.mdx index a61c4b177..ccf4b0466 100644 --- a/fern/products/api-def/ferndef-pages/endpoints/sse.mdx +++ b/fern/products/api-def/ferndef-pages/endpoints/sse.mdx @@ -34,7 +34,7 @@ types: text: string ``` -## Server-sent events +## Server-Sent Events If your API returns server-sent-events, with the `data` and `event` keys as seen below @@ -63,7 +63,7 @@ types: text: string ``` -## `Stream` parameter +## `stream` parameter It has become common practice for endpoints to have a `stream` parameter that controls whether the response is streamed or not. Fern supports this pattern in a first diff --git a/fern/products/api-def/ferndef-pages/types.mdx b/fern/products/api-def/ferndef-pages/types.mdx index 6823bdbb1..c9ef37bcb 100644 --- a/fern/products/api-def/ferndef-pages/types.mdx +++ b/fern/products/api-def/ferndef-pages/types.mdx @@ -138,7 +138,7 @@ types: value: '!=' ``` -### Discriminated Unions +### Discriminated unions Fern supports tagged unions (a.k.a. discriminated unions). Unions are useful for polymorphism. This is similar to the `oneOf` concept in OpenAPI. @@ -196,7 +196,7 @@ This corresponds to a JSON object like this: } ``` -### Undiscriminated Unions +### Undiscriminated unions Undiscriminated unions are similar to discriminated unions, however you don't need to define an explicit discriminant property. diff --git a/fern/products/api-def/ferndef-pages/webhooks.mdx b/fern/products/api-def/ferndef-pages/webhooks.mdx index 3b164f863..81c5984f0 100644 --- a/fern/products/api-def/ferndef-pages/webhooks.mdx +++ b/fern/products/api-def/ferndef-pages/webhooks.mdx @@ -63,7 +63,7 @@ You can inline the schema of the payload by doing the following: ``` -## Generate webhook reference +## Generate Webhook reference Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. diff --git a/fern/products/api-def/ferndef-pages/websockets.mdx b/fern/products/api-def/ferndef-pages/websockets.mdx index ec637659b..8d0af92a6 100644 --- a/fern/products/api-def/ferndef-pages/websockets.mdx +++ b/fern/products/api-def/ferndef-pages/websockets.mdx @@ -24,7 +24,7 @@ A `channel` is defined by the following fields: - `body`: The schema of the message - `examples`: Example WebSocket connection _(Optional)_ -### WebSocket example +### WebSocket example ```yaml @@ -75,9 +75,9 @@ A `channel` is defined by the following fields: ``` -## WebSocket API Reference +## WebSocket API reference -### WebSocket Reference +### WebSocket reference Fern renders a unique reference page for WebSockets. The **Handshake** section outlines the protocol for connecting with the server, while the **Send** and **Receive** sections outline the message schemas that can be sent between the client and server. @@ -85,7 +85,7 @@ Fern renders a unique reference page for WebSockets. The **Handshake** section o The WebSocket Reference -### WebSocket Playground +### WebSocket playground diff --git a/fern/products/api-def/grpc-def.yml b/fern/products/api-def/grpc-def.yml index 0c3929805..2756368b3 100644 --- a/fern/products/api-def/grpc-def.yml +++ b/fern/products/api-def/grpc-def.yml @@ -1,5 +1,5 @@ navigation: - - page: gRPC Definition Redirect Page + - page: gRPC definition redirect page path: ./pages/grpc-empty.mdx slug: empty-page hidden: true diff --git a/fern/products/api-def/grpc-pages/auth.mdx b/fern/products/api-def/grpc-pages/auth.mdx index 81b27418e..f81d20e3d 100644 --- a/fern/products/api-def/grpc-pages/auth.mdx +++ b/fern/products/api-def/grpc-pages/auth.mdx @@ -5,7 +5,7 @@ subtitle: Configure authentication for gRPC services including TLS, JWT, and cus gRPC supports various authentication mechanisms to secure your services. Authentication can be configured at the transport level (TLS) and at the application level (credentials, tokens, etc.). -## Transport Security (TLS) +## Transport security (tls) gRPC strongly recommends using TLS for production services to ensure encrypted communication: @@ -62,7 +62,7 @@ def create_secure_server(): return server ``` -## JWT Authentication +## Jwt authentication Use JWT tokens for stateless authentication: @@ -116,7 +116,7 @@ class AuthServiceServicer(auth_service_pb2_grpc.AuthServiceServicer): ) ``` -## Interceptors for Authentication +## Interceptors for authentication Use gRPC interceptors to handle authentication across all methods: @@ -173,7 +173,7 @@ class AuthInterceptor(grpc.ServerInterceptor): return grpc.unary_unary_rpc_method_handler(abort) ``` -## API Key Authentication +## API key authentication Implement API key-based authentication: @@ -226,7 +226,7 @@ class ApiKeyAuthInterceptor(grpc.ServerInterceptor): return continuation(handler_call_details) ``` -## OAuth2 Integration +## Oauth2 integration Integrate with OAuth2 providers: @@ -270,7 +270,7 @@ class OAuth2Interceptor(grpc.ServerInterceptor): return self._invalid_token_response() ``` -## Client-side Authentication +## Client-side authentication Configure authentication on the client side: @@ -309,7 +309,7 @@ def create_api_key_channel(server_address, api_key): return intercepted_channel ``` -## Role-Based Access Control +## Role-based access control Implement RBAC for fine-grained permissions: diff --git a/fern/products/api-def/grpc-pages/automation.mdx b/fern/products/api-def/grpc-pages/automation.mdx index 048c3b6b4..721b5080d 100644 --- a/fern/products/api-def/grpc-pages/automation.mdx +++ b/fern/products/api-def/grpc-pages/automation.mdx @@ -55,7 +55,7 @@ jobs: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} ``` -## Protocol Buffer validation +## Protocol buffer validation Add validation steps for your Protocol Buffer files: @@ -103,7 +103,7 @@ jobs: Configure Fern to automatically pull Protocol Buffer files from various sources: -### From Git repository +### From git repository ```yaml title="generators.yml" {3-7} api: specs: diff --git a/fern/products/api-def/grpc-pages/overview.mdx b/fern/products/api-def/grpc-pages/overview.mdx index c8abe0852..481f465e0 100644 --- a/fern/products/api-def/grpc-pages/overview.mdx +++ b/fern/products/api-def/grpc-pages/overview.mdx @@ -159,7 +159,7 @@ enum ChatMessageType { } ``` -## Set up your fern folder +## Set up your Fern folder Need help getting started with gRPC and Fern? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) diff --git a/fern/products/api-def/grpc-pages/servers.mdx b/fern/products/api-def/grpc-pages/servers.mdx index 3e1b6c41d..3bd3ad53c 100644 --- a/fern/products/api-def/grpc-pages/servers.mdx +++ b/fern/products/api-def/grpc-pages/servers.mdx @@ -6,7 +6,7 @@ subtitle: Set up and configure gRPC servers for production deployments gRPC servers can be configured with various options for security, performance, and scalability. Proper server configuration is crucial for production deployments. -## Basic Server Setup +## Basic server setup Set up a basic gRPC server with multiple services: @@ -41,7 +41,7 @@ if __name__ == '__main__': server.wait_for_termination() ``` -## TLS Configuration +## Tls configuration Configure TLS for secure production deployments: @@ -78,7 +78,7 @@ def create_secure_server(): return server ``` -## Server Options +## Server options Configure various server options for performance and behavior: @@ -111,7 +111,7 @@ def create_configured_server(): return server ``` -## Health Checking +## Health checking Implement health checking for load balancer integration: @@ -208,7 +208,7 @@ def create_server_with_reflection(): return server ``` -## Load Balancing +## Load balancing Configure client-side load balancing: @@ -244,7 +244,7 @@ def create_multi_target_channel(): return channel ``` -## Kubernetes Deployment +## Kubernetes deployment Deploy gRPC services on Kubernetes: @@ -295,7 +295,7 @@ spec: type: ClusterIP ``` -## Monitoring and Observability +## Monitoring and observability Add monitoring and tracing to your gRPC server: @@ -354,7 +354,7 @@ def create_monitored_server(): return server ``` -## Environment-specific Configuration +## Environment-specific configuration Configure servers for different environments: diff --git a/fern/products/api-def/grpc-pages/services/errors.mdx b/fern/products/api-def/grpc-pages/services/errors.mdx index 91b3c15fd..b1c8eb87a 100644 --- a/fern/products/api-def/grpc-pages/services/errors.mdx +++ b/fern/products/api-def/grpc-pages/services/errors.mdx @@ -5,7 +5,7 @@ subtitle: Implement robust error handling with gRPC status codes and custom erro gRPC provides a comprehensive error handling system using status codes, error messages, and optional error details. Proper error handling ensures clients can respond appropriately to different failure scenarios. -## gRPC Status Codes +## gRPC status codes gRPC uses standard status codes to indicate the outcome of RPC calls: @@ -53,7 +53,7 @@ enum ErrorCode { } ``` -## Standard Error Handling +## Standard error handling Implement standard gRPC error responses: @@ -202,7 +202,7 @@ class ErrorDemoServiceServicer(errors_pb2_grpc.ErrorDemoServiceServicer): ]) ``` -## Custom Error Types +## Custom error types Define custom error types for domain-specific errors: @@ -342,7 +342,7 @@ class UserService(user_pb2_grpc.UserServiceServicer): # Continue with user creation... ``` -## Error Interceptors +## Error interceptors Implement global error handling with interceptors: @@ -404,7 +404,7 @@ class ErrorInterceptor(grpc.ServerInterceptor): return None ``` -## Client-side Error Handling +## Client-side error handling Handle errors on the client side: @@ -497,7 +497,7 @@ def create_user_with_error_handling(stub, user_data): return response ``` -## Error Response Patterns +## Error response patterns Define consistent error response patterns: diff --git a/fern/products/api-def/grpc-pages/services/grpc-services.mdx b/fern/products/api-def/grpc-pages/services/grpc-services.mdx index 0a80e65e3..0245d6921 100644 --- a/fern/products/api-def/grpc-pages/services/grpc-services.mdx +++ b/fern/products/api-def/grpc-pages/services/grpc-services.mdx @@ -5,7 +5,7 @@ subtitle: Define gRPC services with RPCs, messages, and Protocol Buffer schemas gRPC services are the core building blocks of your API. Each service defines a collection of remote procedure calls (RPCs) that clients can invoke, along with the message types used for requests and responses. -## Service Definition +## Service definition Define a gRPC service in a `.proto` file: @@ -79,7 +79,7 @@ enum ThemeMode { } ``` -## Request and Response Messages +## Request and response messages Define clear request and response message types: @@ -147,7 +147,7 @@ message SearchMetadata { } ``` -## Service Implementation +## Service implementation Implement the service in your preferred language: @@ -335,9 +335,9 @@ class UserServiceServicer(user_service_pb2_grpc.UserServiceServicer): return user_service_pb2.SearchUsersResponse() ``` -## Protocol Buffer Best Practices +## Protocol buffer best practices -### Field Numbers +### Field numbers - Use field numbers 1-15 for frequently used fields (more efficient encoding) - Reserve field numbers for removed fields to maintain compatibility - Never reuse field numbers @@ -359,7 +359,7 @@ message User { } ``` -### Naming Conventions +### Naming conventions - Use `snake_case` for field names - Use `PascalCase` for message and service names - Use `UPPER_SNAKE_CASE` for enum values @@ -392,7 +392,7 @@ package userservice.v1; // Version in package name option go_package = "example.com/userservice/v1"; ``` -## Multiple Services +## Multiple services Organize related functionality into separate services: diff --git a/fern/products/api-def/grpc-pages/services/streaming.mdx b/fern/products/api-def/grpc-pages/services/streaming.mdx index 69344d7a0..2a71862a9 100644 --- a/fern/products/api-def/grpc-pages/services/streaming.mdx +++ b/fern/products/api-def/grpc-pages/services/streaming.mdx @@ -5,7 +5,7 @@ subtitle: Implement server streaming, client streaming, and bidirectional stream gRPC supports four types of service methods: unary, server streaming, client streaming, and bidirectional streaming. Streaming enables efficient real-time communication and large data transfers. -## Server Streaming +## Server streaming Server streaming allows the server to send multiple responses to a single client request: @@ -141,7 +141,7 @@ class StreamingServiceServicer(streaming_pb2_grpc.StreamingServiceServicer): context.set_details(f'Error downloading file: {str(e)}') ``` -## Client Streaming +## Client streaming Client streaming allows the client to send multiple requests and receive a single response: @@ -258,7 +258,7 @@ class StreamingServiceServicer(streaming_pb2_grpc.StreamingServiceServicer): os.remove(file_path) ``` -## Bidirectional Streaming +## Bidirectional streaming Bidirectional streaming allows both client and server to send multiple messages: @@ -394,9 +394,9 @@ class StreamingServiceServicer(streaming_pb2_grpc.StreamingServiceServicer): self.chat_service.leave_room(user_session) ``` -## Streaming Best Practices +## Streaming best practices -### Flow Control +### Flow control Implement proper flow control to prevent overwhelming clients: ```python title="flow_control.py" @@ -432,7 +432,7 @@ def StreamData(self, request, context): producer_thread.join(timeout=1) ``` -### Error Handling in Streams +### Error handling in streams Handle errors gracefully in streaming operations: ```python title="stream_error_handling.py" @@ -465,7 +465,7 @@ def StreamWithErrorHandling(self, request, context): context.set_details(f'Stream failed: {str(e)}') ``` -### Client-side Streaming +### Client-side streaming Handle streaming on the client side: diff --git a/fern/products/api-def/openapi-def.yml b/fern/products/api-def/openapi-def.yml index 42490e7fe..77d6c9ae3 100644 --- a/fern/products/api-def/openapi-def.yml +++ b/fern/products/api-def/openapi-def.yml @@ -1,5 +1,5 @@ navigation: - - page: OpenAPI Definition Redirect Page + - page: OpenAPI definition redirect page path: ./pages/openapi-empty.mdx slug: empty-page hidden: true diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 22af42aec..3fcddb4ee 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -126,7 +126,7 @@ client = new Client({ }) ``` -## ApiKey security scheme +## Apikey security scheme Start by defining an `apiKey` security scheme in your `openapi.yml`: @@ -231,11 +231,11 @@ api: -#### get-token +#### Get-token -#### refresh-token +#### Refresh-token diff --git a/fern/products/api-def/openapi-pages/automation.mdx b/fern/products/api-def/openapi-pages/automation.mdx index 8258c8420..34b1b36d9 100644 --- a/fern/products/api-def/openapi-pages/automation.mdx +++ b/fern/products/api-def/openapi-pages/automation.mdx @@ -57,6 +57,6 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y This creates daily pull requests with any API spec updates. To change the frequency, modify the `cron` schedule (see GitHub's [schedule syntax](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule)). -## Other use cases +## Other use cases If your OpenAPI spec lives in a different repository (rather than at a public URL), you can sync it to your Fern folder using explicit file mappings. See the [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi) for this and other advanced configurations. diff --git a/fern/products/api-def/openapi-pages/endpoints/multipart.mdx b/fern/products/api-def/openapi-pages/endpoints/multipart.mdx index 800fa0fa1..0c350da5c 100644 --- a/fern/products/api-def/openapi-pages/endpoints/multipart.mdx +++ b/fern/products/api-def/openapi-pages/endpoints/multipart.mdx @@ -49,7 +49,7 @@ Any request body that is defined with a `multipart/form-data` content type, will treated as a multipart request. Within a given multipart request, a string parameter with `format:binary` will represent an arbitrary file. -## Array of Files +## Array of files If your endpoint supports an array of files, then your request body must use an array type. diff --git a/fern/products/api-def/openapi-pages/endpoints/sse.mdx b/fern/products/api-def/openapi-pages/endpoints/sse.mdx index 05b898fac..af718c66d 100644 --- a/fern/products/api-def/openapi-pages/endpoints/sse.mdx +++ b/fern/products/api-def/openapi-pages/endpoints/sse.mdx @@ -37,7 +37,7 @@ components: type: string ``` -## Server-sent events +## Server-Sent Events @@ -72,7 +72,7 @@ components: type: string ``` -## `Stream` parameter +## `stream` parameter It has become common practice for endpoints to have a `stream` parameter that controls whether the response is streamed or not. Fern supports this pattern in a first diff --git a/fern/products/api-def/openapi-pages/overview.mdx b/fern/products/api-def/openapi-pages/overview.mdx index 8335a4d06..9a670088f 100644 --- a/fern/products/api-def/openapi-pages/overview.mdx +++ b/fern/products/api-def/openapi-pages/overview.mdx @@ -1,166 +1,166 @@ ---- -title: What is an OpenAPI Specification? -description: OpenAPI is a standard for documenting REST APIs ---- - -The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification is -written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes. -Fern is compatible with the latest OAS release, which is currently [v3.1.1](https://spec.openapis.org/#openapi-specification). - -Below is an example of an OpenAPI file: - -```yaml title="openapi.yml" maxLines=10 -openapi: 3.0.2 -info: - title: Petstore - OpenAPI 3.0 - description: |- - This is a sample Pet Store Server based on the OpenAPI 3.0 specification. -paths: - "/pet": - put: - tags: - - pet - summary: Update an existing pet - description: Update an existing pet by Id - operationId: updatePet - requestBody: - description: Update an existent pet in the store - content: - application/json: - schema: - "$ref": "#/components/schemas/Pet" - required: true - responses: - '200': - description: Successful operation - content: - application/json: - schema: - "$ref": "#/components/schemas/Pet" - '400': - description: Invalid ID supplied - '404': - description: Pet not found - '405': - description: Validation exception - security: - - api_key -components: - schemas: - Category: - type: object - properties: - id: - type: integer - format: int64 - example: 1 - name: - type: string - example: Dogs - Tag: - type: object - properties: - id: - type: integer - format: int64 - name: - type: string - Pet: - required: - - name - - photoUrls - type: object - properties: - id: - type: integer - format: int64 - example: 10 - name: - type: string - example: doggie - category: - "$ref": "#/components/schemas/Category" - photoUrls: - type: array - items: - type: string - tags: - type: array - items: - "$ref": "#/components/schemas/Tag" - status: - type: string - description: pet status in the store - enum: - - available - - pending - - sold - securitySchemes: - api_key: - type: apiKey - name: api_key - in: header -``` -## Best practices - -Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation: - -- **Organize with proper project structure.** Follow the instructions at [Project structure](/api-definitions/overview/project-structure) to clearly organize the directories that contain your definition and other related files. -- **Add `operationId` to endpoints.** Include a clear `operationId` for each endpoint to control the function names generated in your SDKs. (Or use [extensions to customize group and method names](/api-definitions/openapi/extensions/method-names).) -- **Reference schemas instead of inlining.** Define reusable schemas in the `components/schemas` section and reference them with `$ref`. This promotes consistency, reduces duplication, and makes maintenance easier. - - ```yaml title="openapi.yml" {8, 14, 17-25} - paths: - /pets: - post: - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Pet' # Clean reference - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Pet' # Reused easily - components: - schemas: - Pet: # Defined once, used everywhere - type: object - properties: - name: - type: string - status: - type: string - enum: [available, pending, sold] - ``` - -- **Use overrides and Fern extensions for customization.** Customize your specification using Fern [extensions](/api-definitions/openapi/extensions/overview) housed in an [overrides file](/api-definitions/overview/overrides). This lets you modify generation behavior without changing your core OpenAPI definition. - -Once your OpenAPI spec follows these practices, you're ready to set up your fern folder. - -## Set up your fern folder - - Considering options to generate an OpenAPI spec? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) - -Start by initializing your fern folder with an OpenAPI spec - - -```sh file -fern init --openapi ./path/to/openapi -``` -```sh url -fern init --openapi https://host/path/to/openapi -``` - - -This will initialize a directory like the following -``` -fern/ - ├─ fern.config.json - ├─ generators.yml - └─ openapi/ - ├─ openapi.yml -``` - +--- +title: What is an OpenAPI Specification? +description: OpenAPI is a standard for documenting REST APIs +--- + +The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification is +written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes. +Fern is compatible with the latest OAS release, which is currently [v3.1.1](https://spec.openapis.org/#openapi-specification). + +Below is an example of an OpenAPI file: + +```yaml title="openapi.yml" maxLines=10 +openapi: 3.0.2 +info: + title: Petstore - OpenAPI 3.0 + description: |- + This is a sample Pet Store Server based on the OpenAPI 3.0 specification. +paths: + "/pet": + put: + tags: + - pet + summary: Update an existing pet + description: Update an existing pet by Id + operationId: updatePet + requestBody: + description: Update an existent pet in the store + content: + application/json: + schema: + "$ref": "#/components/schemas/Pet" + required: true + responses: + '200': + description: Successful operation + content: + application/json: + schema: + "$ref": "#/components/schemas/Pet" + '400': + description: Invalid ID supplied + '404': + description: Pet not found + '405': + description: Validation exception + security: + - api_key +components: + schemas: + Category: + type: object + properties: + id: + type: integer + format: int64 + example: 1 + name: + type: string + example: Dogs + Tag: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + Pet: + required: + - name + - photoUrls + type: object + properties: + id: + type: integer + format: int64 + example: 10 + name: + type: string + example: doggie + category: + "$ref": "#/components/schemas/Category" + photoUrls: + type: array + items: + type: string + tags: + type: array + items: + "$ref": "#/components/schemas/Tag" + status: + type: string + description: pet status in the store + enum: + - available + - pending + - sold + securitySchemes: + api_key: + type: apiKey + name: api_key + in: header +``` +## Best practices + +Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation: + +- **Organize with proper project structure.** Follow the instructions at [Project structure](/api-definitions/overview/project-structure) to clearly organize the directories that contain your definition and other related files. +- **Add `operationId` to endpoints.** Include a clear `operationId` for each endpoint to control the function names generated in your SDKs. (Or use [extensions to customize group and method names](/api-definitions/openapi/extensions/method-names).) +- **Reference schemas instead of inlining.** Define reusable schemas in the `components/schemas` section and reference them with `$ref`. This promotes consistency, reduces duplication, and makes maintenance easier. + + ```yaml title="openapi.yml" {8, 14, 17-25} + paths: + /pets: + post: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' # Clean reference + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' # Reused easily + components: + schemas: + Pet: # Defined once, used everywhere + type: object + properties: + name: + type: string + status: + type: string + enum: [available, pending, sold] + ``` + +- **Use overrides and Fern extensions for customization.** Customize your specification using Fern [extensions](/api-definitions/openapi/extensions/overview) housed in an [overrides file](/api-definitions/overview/overrides). This lets you modify generation behavior without changing your core OpenAPI definition. + +Once your OpenAPI spec follows these practices, you're ready to set up your fern folder. + +## Set up your Fern folder + + Considering options to generate an OpenAPI spec? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) + +Start by initializing your fern folder with an OpenAPI spec + + +```sh file +fern init --openapi ./path/to/openapi +``` +```sh url +fern init --openapi https://host/path/to/openapi +``` + + +This will initialize a directory like the following +``` +fern/ + ├─ fern.config.json + ├─ generators.yml + └─ openapi/ + ├─ openapi.yml +``` + diff --git a/fern/products/api-def/openapi-pages/servers.mdx b/fern/products/api-def/openapi-pages/servers.mdx index 28ce155a2..2e11ba0ca 100644 --- a/fern/products/api-def/openapi-pages/servers.mdx +++ b/fern/products/api-def/openapi-pages/servers.mdx @@ -30,7 +30,7 @@ servers: url: https://api.eu.yourcompany.com/ ``` -## Multiple Base URLs for a single API +## Multiple base URLs for a single API If you have a microservice architecture, it is possible that you may have different endpoints hosted at different URLs. For example, your AI endpoints might be hosted at `ai.yourcompany.com` and the rest diff --git a/fern/products/api-def/openapi-pages/webhooks.mdx b/fern/products/api-def/openapi-pages/webhooks.mdx index 92ff56d62..4fb812a6f 100644 --- a/fern/products/api-def/openapi-pages/webhooks.mdx +++ b/fern/products/api-def/openapi-pages/webhooks.mdx @@ -8,7 +8,7 @@ Fern supports two methods for defining webhooks in your OpenAPI specification: 1. Using OpenAPI 3.1's native webhook support (recommended) 2. Using Fern's `x-fern-webhook` extension -## OpenAPI 3.1 webhooks +## OpenAPI 3.1 Webhooks For OpenAPI 3.1 specifications, use the `webhooks` top-level field to define your webhook operations. Each webhook requires an `operationId` to be properly processed by Fern. @@ -66,7 +66,7 @@ webhooks: description: Return a 200 status to indicate that the data was received successfully ``` -## Fern webhook extension +## Fern Webhook extension For OpenAPI 3.0, use the `x-fern-webhook: true` extension to define webhooks. Fern will treat the `requestBody` as the webhook payload. @@ -103,7 +103,7 @@ The path that you choose when defining a webhook can be arbitrary. Since webhook can be sent to any server, Fern just ignores the path. -## Generate webhook reference +## Generate Webhook reference Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. diff --git a/fern/products/api-def/openrpc-def.yml b/fern/products/api-def/openrpc-def.yml index f1522a99f..33bc1a585 100644 --- a/fern/products/api-def/openrpc-def.yml +++ b/fern/products/api-def/openrpc-def.yml @@ -1,5 +1,5 @@ navigation: - - page: OpenRPC Definition Redirect Page + - page: OpenRPC definition redirect page path: ./pages/openrpc-empty.mdx slug: empty-page hidden: true diff --git a/fern/products/api-def/openrpc-pages/auth.mdx b/fern/products/api-def/openrpc-pages/auth.mdx index aefa3f0e6..08f94042c 100644 --- a/fern/products/api-def/openrpc-pages/auth.mdx +++ b/fern/products/api-def/openrpc-pages/auth.mdx @@ -5,11 +5,11 @@ subtitle: Model auth schemes for JSON-RPC APIs including bearer, basic, and api Authentication in OpenRPC can be configured at the server level or method level, depending on your JSON-RPC implementation. Unlike REST APIs, JSON-RPC typically handles authentication through the transport layer (HTTP headers) or within the JSON-RPC request payload. -## HTTP Transport Authentication +## HTTP transport authentication When using HTTP as the transport for JSON-RPC, you can use standard HTTP authentication schemes. -### Bearer Token Authentication +### Bearer token authentication Configure bearer token authentication for HTTP-based JSON-RPC: @@ -42,7 +42,7 @@ const client = new JSONRPCClient({ const result = await client.call("calculate.add", { a: 5, b: 3 }); ``` -### API Key Authentication +### API key authentication Configure API key authentication: @@ -72,7 +72,7 @@ const client = new JSONRPCClient({ }); ``` -### Basic Authentication +### Basic authentication Configure basic authentication: @@ -102,7 +102,7 @@ const client = new JSONRPCClient({ }); ``` -## Method-Level Authentication +## Method-level authentication Some JSON-RPC implementations may require different authentication for specific methods: @@ -132,7 +132,7 @@ methods: $ref: '#/components/schemas/UserProfile' ``` -## WebSocket Authentication +## WebSocket authentication For WebSocket transport, authentication typically happens during connection establishment: @@ -156,7 +156,7 @@ components: description: Authentication token passed as query parameter ``` -## Custom Authentication Parameters +## Custom authentication parameters For JSON-RPC APIs that handle authentication within the request payload: @@ -190,7 +190,7 @@ methods: type: string ``` -## Fern Extensions for Authentication +## Fern extensions for authentication Use Fern extensions to customize authentication behavior: @@ -207,7 +207,7 @@ components: This allows users to set authentication via environment variables or constructor parameters, making the SDK more flexible and secure. -## Error Handling for Authentication +## Error handling for authentication Define standardized error responses for authentication failures: diff --git a/fern/products/api-def/openrpc-pages/automation.mdx b/fern/products/api-def/openrpc-pages/automation.mdx index b967c544a..f65d2f821 100644 --- a/fern/products/api-def/openrpc-pages/automation.mdx +++ b/fern/products/api-def/openrpc-pages/automation.mdx @@ -85,7 +85,7 @@ api: version: 0.8.8 ``` -### From Git repository +### From git repository ```yaml title="generators.yml" {3-7} api: specs: @@ -181,7 +181,7 @@ jobs: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} ``` -## Code generation from JSON-RPC server +## Code generation from json-rpc server For servers that can generate their own OpenRPC specifications: @@ -281,7 +281,7 @@ environments: path: ./generated-sdk ``` -## JSON-RPC server introspection +## Json-rpc server introspection For servers that support OpenRPC discovery: diff --git a/fern/products/api-def/openrpc-pages/extensions/method-names.mdx b/fern/products/api-def/openrpc-pages/extensions/method-names.mdx index d9e0528dd..67da275a4 100644 --- a/fern/products/api-def/openrpc-pages/extensions/method-names.mdx +++ b/fern/products/api-def/openrpc-pages/extensions/method-names.mdx @@ -51,7 +51,7 @@ const order = await client.order.create({ orderData: {...} }); Follow these conventions when naming SDK methods: -### CRUD operations +### Crud operations Use standard CRUD naming: ```yaml title="openrpc.yml" {4-5} diff --git a/fern/products/api-def/openrpc-pages/overview.mdx b/fern/products/api-def/openrpc-pages/overview.mdx index 4d13ee3d0..70ed28b6d 100644 --- a/fern/products/api-def/openrpc-pages/overview.mdx +++ b/fern/products/api-def/openrpc-pages/overview.mdx @@ -144,7 +144,7 @@ components: - timestamp ``` -## Set up your fern folder +## Set up your Fern folder Considering options to generate an OpenRPC spec? Get live support [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email) diff --git a/fern/products/api-def/openrpc-pages/servers.mdx b/fern/products/api-def/openrpc-pages/servers.mdx index f00bf68c6..86483f8de 100644 --- a/fern/products/api-def/openrpc-pages/servers.mdx +++ b/fern/products/api-def/openrpc-pages/servers.mdx @@ -24,7 +24,7 @@ Specifying servers is valuable for both SDKs and Docs: JSON-RPC can be used over various transport protocols: -### HTTP/HTTPS Transport +### Http/https transport ```yml openrpc.yml servers: - name: http-production @@ -35,7 +35,7 @@ servers: description: Staging HTTPS endpoint ``` -### WebSocket Transport +### WebSocket transport ```yml openrpc.yml servers: - name: websocket-production @@ -46,7 +46,7 @@ servers: description: Development WebSocket server ``` -### TCP Transport +### Tcp transport ```yml openrpc.yml servers: - name: tcp-production @@ -133,7 +133,7 @@ servers: description: EU regional server ``` -## WebSocket-specific configurations +## Websocket-specific configurations Configure WebSocket servers with connection parameters: diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx index b1b03a590..8e4b2aa87 100644 --- a/fern/products/api-def/pages/overrides.mdx +++ b/fern/products/api-def/pages/overrides.mdx @@ -96,7 +96,7 @@ paths: -## Separate overrides for SDKs and Docs +## Separate overrides for SDKs and docs For separate SDK and documentation configurations, you can use different override files in separate folders with their own `generators.yml` files. diff --git a/fern/products/api-def/pages/what-is-an-api-definition.mdx b/fern/products/api-def/pages/what-is-an-api-definition.mdx index ff7dd3f1a..74403c8ab 100644 --- a/fern/products/api-def/pages/what-is-an-api-definition.mdx +++ b/fern/products/api-def/pages/what-is-an-api-definition.mdx @@ -1,358 +1,358 @@ ---- -title: What is an API definition? -description: Describes the contract between the API provider and API consumer ---- - -An API definition is a machine-readable specification of your API's structure, including **endpoints**, **request and response schemas**, and **authentication** requirements. Instead of manually keeping SDKs and documentation in sync with API changes, an API definition enables automatic generation of these artifacts. - -Fern integrates with several API definition formats: - - - - Formerly known as Swagger, [OpenAPI](https://swagger.io/specification/) is the most popular API definition format. - OpenAPI can be used to document RESTful APIs and is defined in a YAML or JSON file. - - Check out an example OpenAPI Specification for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) - - ```yaml maxLines={0} - openapi: 3.0.2 - tags: - - name: pet - description: Everything about your Pets - paths: - /pet: - post: - tags: - - pet - summary: Add a new pet to the store - description: Add a new pet to the store - operationId: addPet - requestBody: - description: Create a new pet in the store - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/Pet' - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Pet' - responses: - '200': - description: Successful operation - content: - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/json: - schema: - $ref: '#/components/schemas/Pet' - '405': - description: Invalid input - components: - schemas: - Pet: - required: - - name - - photoUrls - properties: - id: - type: integer - format: int64 - example: 10 - name: - type: string - example: doggie - category: - $ref: '#/components/schemas/Category' - photoUrls: - type: array - xml: - wrapped: true - items: - type: string - xml: - name: photoUrl - tags: - type: array - xml: - wrapped: true - items: - $ref: '#/components/schemas/Tag' - xml: - name: tag - status: - type: string - description: pet status in the store - enum: - - available - - pending - - sold - xml: - name: pet - type: object - ``` - - - [AsyncAPI](https://v2.asyncapi.com/docs) is a specification for defining event-driven APIs. It is used to document APIs that use - WebSockets, MQTT, and other messaging protocols. - - Check out an example AsyncAPI spec for a chat application below: - - ```yaml maxLines={0} - asyncapi: 2.0.0 - info: - title: Chat server - version: 1.0.0 - - servers: - Production: - url: chat.com - protocol: ws - - channels: - "/application": - bindings: - ws: - query: - type: object - properties: - apiKey: - type: string - description: The API key for the client - minimum: 1 - bindingVersion: 0.1.0 - subscribe: - operationId: sendMessage - message: - $ref: '#/components/messages/SendMessage' - publish: - operationId: receiveMessage - message: - $ref: '#/components/messages/ReceiveMessage' - - components: - messages: - SendMessage: - payload: - message: string - ReceiveMessage: - payload: - message: string - from: - type: string - description: The userId for the sender of the message - ``` - - - - [OpenRPC](https://open-rpc.org/) is a spec for describing JSON-RPC 2.0 APIs. It enables interactive docs and code generation tooling to the JSON-RPC ecosystem. - - Check out an example OpenRPC Specification for a crypto wallet service below: - - ```yaml maxLines=0 - # yaml-language-server: $schema=https://meta.open-rpc.org/ - $schema: https://meta.open-rpc.org/ - openrpc: 1.2.4 - info: - title: Basic Wallet API JSON-RPC Specification - description: A simple JSON-RPC API for querying wallet balances. - version: 0.0.1 - servers: - - url: https://wallet.example.com/json-rpc - name: Mainnet - methods: - - name: getBalance - description: Get the balance of a wallet address. - params: - - name: address - required: true - description: The wallet address to query. - schema: - type: string - result: - name: balance - description: The balance of the wallet address. - schema: - type: number - examples: - - name: getBalance example - params: - - name: address - value: "0x1234567890abcdef1234567890abcdef12345678" - result: - name: balance - value: 42.5 - ``` - - - [gRPC](https://grpc.io/) is a modern, open-source RPC framework developed by Google. It uses Protocol Buffers as its interface definition language and supports multiple programming languages with efficient binary serialization. - - gRPC APIs are defined using Protocol Buffer (.proto) files that specify services and message types. Check out an example gRPC service definition below: - - ```proto maxLines={0} - syntax = "proto3"; - - package petstore; - - // The pet store service definition - service PetStoreService { - // Get a pet by ID - rpc GetPet(GetPetRequest) returns (Pet); - - // Add a new pet to the store - rpc AddPet(AddPetRequest) returns (Pet); - - // List all pets with optional filtering - rpc ListPets(ListPetsRequest) returns (ListPetsResponse); - } - - // Request message for getting a pet - message GetPetRequest { - int64 pet_id = 1; - } - - // Request message for adding a pet - message AddPetRequest { - string name = 1; - string category = 2; - repeated string photo_urls = 3; - PetStatus status = 4; - } - - // Request message for listing pets - message ListPetsRequest { - int32 page_size = 1; - string page_token = 2; - PetStatus status = 3; - } - - // Response message for listing pets - message ListPetsResponse { - repeated Pet pets = 1; - string next_page_token = 2; - } - - // Pet message definition - message Pet { - int64 id = 1; - string name = 2; - string category = 3; - repeated string photo_urls = 4; - PetStatus status = 5; - } - - // Pet status enumeration - enum PetStatus { - PET_STATUS_UNSPECIFIED = 0; - PET_STATUS_AVAILABLE = 1; - PET_STATUS_PENDING = 2; - PET_STATUS_SOLD = 3; - } - ``` - - - The Fern Definition is our take on a simpler API definition format. It is designed with **best-practices**, - supports **both RESTful and event-driven APIs**, and is optimized for **SDK generation**. - - - The Fern Definition is inspired from internal API Definition formats built at companies like - [Amazon](https://smithy.io/2.0/index.html), [Google](https://grpc.io/), [Palantir](https://blog.palantir.com/introducing-conjure-palantirs-toolchain-for-http-json-apis-2175ec172d32), - Twilio and Stripe. These companies **rejected** OpenAPI and built their own version. - - - Check out an example Fern Definition below: - - ```yaml maxLines={0} - types: - MovieId: string - - Movie: - properties: - id: MovieId - title: string - rating: - type: double - docs: The rating scale is one to five stars - - CreateMovieRequest: - properties: - title: string - rating: double - - service: - auth: false - base-path: /movies - endpoints: - createMovie: - docs: Add a movie to the database - method: POST - path: /create-movie - request: CreateMovieRequest - response: MovieId - - getMovie: - method: GET - path: /{movieId} - path-parameters: - movieId: MovieId - response: Movie - errors: - - MovieDoesNotExistError - - errors: - MovieDoesNotExistError: - status-code: 404 - type: MovieId - ``` - - - - -## Why create an API definition? - -Once you have an API definition, Fern uses it as an input to generate artifacts -like SDKs and API Reference documentation. Every time you update the API definition, -you can regenerate these artifacts to ensure they are always up-to-date. - - - - Client libraries in multiple languages that automatically stay in sync with your API. - - - Interactive API docs with code examples and live testing capabilities. - - } - href="/docs/integrations/postman" - > - Ready-to-use collection with pre-filled example requests and responses. - - } - href="/api-definitions/openapi/frameworks/fastapi" - > - Pydantic models for FastAPI or controllers for your Spring Boot application. - - +--- +title: What is an API definition? +description: Describes the contract between the API provider and API consumer +--- + +An API definition is a machine-readable specification of your API's structure, including **endpoints**, **request and response schemas**, and **authentication** requirements. Instead of manually keeping SDKs and documentation in sync with API changes, an API definition enables automatic generation of these artifacts. + +Fern integrates with several API definition formats: + + + + Formerly known as Swagger, [OpenAPI](https://swagger.io/specification/) is the most popular API definition format. + OpenAPI can be used to document RESTful APIs and is defined in a YAML or JSON file. + + Check out an example OpenAPI Specification for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) + + ```yaml maxLines={0} + openapi: 3.0.2 + tags: + - name: pet + description: Everything about your Pets + paths: + /pet: + post: + tags: + - pet + summary: Add a new pet to the store + description: Add a new pet to the store + operationId: addPet + requestBody: + description: Create a new pet in the store + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Pet' + responses: + '200': + description: Successful operation + content: + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/json: + schema: + $ref: '#/components/schemas/Pet' + '405': + description: Invalid input + components: + schemas: + Pet: + required: + - name + - photoUrls + properties: + id: + type: integer + format: int64 + example: 10 + name: + type: string + example: doggie + category: + $ref: '#/components/schemas/Category' + photoUrls: + type: array + xml: + wrapped: true + items: + type: string + xml: + name: photoUrl + tags: + type: array + xml: + wrapped: true + items: + $ref: '#/components/schemas/Tag' + xml: + name: tag + status: + type: string + description: pet status in the store + enum: + - available + - pending + - sold + xml: + name: pet + type: object + ``` + + + [AsyncAPI](https://v2.asyncapi.com/docs) is a specification for defining event-driven APIs. It is used to document APIs that use + WebSockets, MQTT, and other messaging protocols. + + Check out an example AsyncAPI spec for a chat application below: + + ```yaml maxLines={0} + asyncapi: 2.0.0 + info: + title: Chat server + version: 1.0.0 + + servers: + Production: + url: chat.com + protocol: ws + + channels: + "/application": + bindings: + ws: + query: + type: object + properties: + apiKey: + type: string + description: The API key for the client + minimum: 1 + bindingVersion: 0.1.0 + subscribe: + operationId: sendMessage + message: + $ref: '#/components/messages/SendMessage' + publish: + operationId: receiveMessage + message: + $ref: '#/components/messages/ReceiveMessage' + + components: + messages: + SendMessage: + payload: + message: string + ReceiveMessage: + payload: + message: string + from: + type: string + description: The userId for the sender of the message + ``` + + + + [OpenRPC](https://open-rpc.org/) is a spec for describing JSON-RPC 2.0 APIs. It enables interactive docs and code generation tooling to the JSON-RPC ecosystem. + + Check out an example OpenRPC Specification for a crypto wallet service below: + + ```yaml maxLines=0 + # yaml-language-server: $schema=https://meta.open-rpc.org/ + $schema: https://meta.open-rpc.org/ + openrpc: 1.2.4 + info: + title: Basic Wallet API JSON-RPC Specification + description: A simple JSON-RPC API for querying wallet balances. + version: 0.0.1 + servers: + - url: https://wallet.example.com/json-rpc + name: Mainnet + methods: + - name: getBalance + description: Get the balance of a wallet address. + params: + - name: address + required: true + description: The wallet address to query. + schema: + type: string + result: + name: balance + description: The balance of the wallet address. + schema: + type: number + examples: + - name: getBalance example + params: + - name: address + value: "0x1234567890abcdef1234567890abcdef12345678" + result: + name: balance + value: 42.5 + ``` + + + [gRPC](https://grpc.io/) is a modern, open-source RPC framework developed by Google. It uses Protocol Buffers as its interface definition language and supports multiple programming languages with efficient binary serialization. + + gRPC APIs are defined using Protocol Buffer (.proto) files that specify services and message types. Check out an example gRPC service definition below: + + ```proto maxLines={0} + syntax = "proto3"; + + package petstore; + + // The pet store service definition + service PetStoreService { + // Get a pet by ID + rpc GetPet(GetPetRequest) returns (Pet); + + // Add a new pet to the store + rpc AddPet(AddPetRequest) returns (Pet); + + // List all pets with optional filtering + rpc ListPets(ListPetsRequest) returns (ListPetsResponse); + } + + // Request message for getting a pet + message GetPetRequest { + int64 pet_id = 1; + } + + // Request message for adding a pet + message AddPetRequest { + string name = 1; + string category = 2; + repeated string photo_urls = 3; + PetStatus status = 4; + } + + // Request message for listing pets + message ListPetsRequest { + int32 page_size = 1; + string page_token = 2; + PetStatus status = 3; + } + + // Response message for listing pets + message ListPetsResponse { + repeated Pet pets = 1; + string next_page_token = 2; + } + + // Pet message definition + message Pet { + int64 id = 1; + string name = 2; + string category = 3; + repeated string photo_urls = 4; + PetStatus status = 5; + } + + // Pet status enumeration + enum PetStatus { + PET_STATUS_UNSPECIFIED = 0; + PET_STATUS_AVAILABLE = 1; + PET_STATUS_PENDING = 2; + PET_STATUS_SOLD = 3; + } + ``` + + + The Fern Definition is our take on a simpler API definition format. It is designed with **best-practices**, + supports **both RESTful and event-driven APIs**, and is optimized for **SDK generation**. + + + The Fern Definition is inspired from internal API Definition formats built at companies like + [Amazon](https://smithy.io/2.0/index.html), [Google](https://grpc.io/), [Palantir](https://blog.palantir.com/introducing-conjure-palantirs-toolchain-for-http-json-apis-2175ec172d32), + Twilio and Stripe. These companies **rejected** OpenAPI and built their own version. + + + Check out an example Fern Definition below: + + ```yaml maxLines={0} + types: + MovieId: string + + Movie: + properties: + id: MovieId + title: string + rating: + type: double + docs: The rating scale is one to five stars + + CreateMovieRequest: + properties: + title: string + rating: double + + service: + auth: false + base-path: /movies + endpoints: + createMovie: + docs: Add a movie to the database + method: POST + path: /create-movie + request: CreateMovieRequest + response: MovieId + + getMovie: + method: GET + path: /{movieId} + path-parameters: + movieId: MovieId + response: Movie + errors: + - MovieDoesNotExistError + + errors: + MovieDoesNotExistError: + status-code: 404 + type: MovieId + ``` + + + + +## Why create an API definition? + +Once you have an API definition, Fern uses it as an input to generate artifacts +like SDKs and API Reference documentation. Every time you update the API definition, +you can regenerate these artifacts to ensure they are always up-to-date. + + + + Client libraries in multiple languages that automatically stay in sync with your API. + + + Interactive API docs with code examples and live testing capabilities. + + } + href="/docs/integrations/postman" + > + Ready-to-use collection with pre-filled example requests and responses. + + } + href="/api-definitions/openapi/frameworks/fastapi" + > + Pydantic models for FastAPI or controllers for your Spring Boot application. + + diff --git a/fern/products/ask-fern/ask-fern.yml b/fern/products/ask-fern/ask-fern.yml index 5415b8d6b..feaf26f25 100644 --- a/fern/products/ask-fern/ask-fern.yml +++ b/fern/products/ask-fern/ask-fern.yml @@ -1,7 +1,7 @@ navigation: - section: Getting started contents: - - page: What is Ask Fern? + - page: What is ask fern? path: ./pages/getting-started/what-is-ask-fern.mdx - page: How it works path: ./pages/getting-started/how-it-works.mdx diff --git a/fern/products/ask-fern/pages/configuration/custom-prompting.mdx b/fern/products/ask-fern/pages/configuration/custom-prompting.mdx index 87200d839..0813de197 100644 --- a/fern/products/ask-fern/pages/configuration/custom-prompting.mdx +++ b/fern/products/ask-fern/pages/configuration/custom-prompting.mdx @@ -7,7 +7,7 @@ Out of the box, our AI Search feature uses default prompts to help fine-tune sea Customizing the system prompt gives you the ability to tailor the AI search responses to best serve your users. You can replace the default prompt with your own prompt to increase the relevance and accuracy of the results. -## Customizing Prompts +## Customizing prompts diff --git a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx index 693ef1191..aae6369c2 100644 --- a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx +++ b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx @@ -17,7 +17,7 @@ ai-search: - discord ``` -### Available Locations +### Available locations Enables Ask Fern on your documentation site. Users will see the AI search interface directly in your docs. @@ -44,7 +44,7 @@ ai-search: title: Company Blog ``` -### Website Datasources +### Website datasources The URL of the website to index. Ask Fern will crawl and index the content from this URL. @@ -54,7 +54,7 @@ ai-search: An optional display name for this datasource. This helps users understand where the information is coming from when Ask Fern cites content from this source. -## Preview Environments +## Preview environments Setting `location: [docs]` enables Ask Fern on preview deployments generated with `fern generate --docs --preview`, allowing you to test the AI search functionality before publishing to production. @@ -62,7 +62,7 @@ Setting `location: [docs]` enables Ask Fern on preview deployments generated wit Preview environments don't interfere with your production Ask Fern deployment. -## Best Practices +## Best practices diff --git a/fern/products/ask-fern/pages/features/slack-app.mdx b/fern/products/ask-fern/pages/features/slack-app.mdx index 96bae1927..51a4d4318 100644 --- a/fern/products/ask-fern/pages/features/slack-app.mdx +++ b/fern/products/ask-fern/pages/features/slack-app.mdx @@ -81,7 +81,7 @@ You can rename the bot to match your brand (example: "YourCompanyName Support"): Now customers will see `@YourCompanyName Support was added to the channel` instead of the default `@Ask Fern` name. -### Collaborative FAQ generation +### Collaborative faq generation You can improve the Slack bot's knowledge base by teaching it from real customer interactions. When the bot provides answers in Slack, you can refine those responses and save them for future reference. diff --git a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx index d236e392e..6cc8776de 100644 --- a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx +++ b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx @@ -45,7 +45,7 @@ Ask Fern helps you: -## Features +## Features diff --git a/fern/products/cli-api-reference/cli-api-reference.yml b/fern/products/cli-api-reference/cli-api-reference.yml index fd7cb9b3c..ddc264a47 100644 --- a/fern/products/cli-api-reference/cli-api-reference.yml +++ b/fern/products/cli-api-reference/cli-api-reference.yml @@ -1,5 +1,5 @@ navigation: - - section: CLI Reference + - section: CLI reference contents: - page: Get started with Fern CLI path: ./pages/cli-get-started.mdx diff --git a/fern/products/cli-api-reference/pages/cli-get-started.mdx b/fern/products/cli-api-reference/pages/cli-get-started.mdx index b61611fdc..9cfb57bb6 100644 --- a/fern/products/cli-api-reference/pages/cli-get-started.mdx +++ b/fern/products/cli-api-reference/pages/cli-get-started.mdx @@ -56,7 +56,7 @@ npm fern generate # Generate outputs -## CLI quickstart +## CLI Quickstart Get started with these commonly used commands: diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 10febd0d8..710872cf7 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -15,14 +15,14 @@ hideOnThisPage: true | [`fern export`](#fern-export) | Export an OpenAPI spec for your API | | [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec | -## Documentation Commands +## Documentation commands | Command | Description | |---------|-------------| | [`fern docs dev`](#fern-docs-dev) | Run local documentation preview server | | [`fern generate --docs`](#fern-generate---docs) | Build & publish documentation updates | -## SDK Generation Commands +## SDK generation commands | Command | Description | |---------|-------------| @@ -31,7 +31,7 @@ hideOnThisPage: true | [`fern write-overrides`](#fern-write-overrides) | Create OpenAPI customizations | | [`fern generator upgrade`](#fern-generator-upgrade) | Update SDK generators to latest versions | -## Detailed Command Documentation +## Detailed command documentation diff --git a/fern/products/cli-api-reference/pages/global-options.mdx b/fern/products/cli-api-reference/pages/global-options.mdx index 15be225ff..db909697b 100644 --- a/fern/products/cli-api-reference/pages/global-options.mdx +++ b/fern/products/cli-api-reference/pages/global-options.mdx @@ -4,7 +4,7 @@ description: 'Global options for the Fern CLI' subtitle: 'Explore Fern CLI global options.' --- -## Quick Reference +## Quick reference | Option | Description | Example | |--------|-------------|---------| @@ -22,7 +22,7 @@ When troubleshooting: The following sections describe each global option in detail. -## help +## Help Use the `--help` option with any Fern CLI command to see an explanation and available options. @@ -56,7 +56,7 @@ Options: ``` -## log-level +## Log-level Use the `--log-level` option to set the verbosity of Fern's logging output. The default level is `info`. @@ -70,7 +70,7 @@ Available levels (from most to least verbose): fern generate --log-level debug ``` -## api +## API Use the `--api` option to target a specific API. This is particularly useful when your project contains multiple API definitions. The API name should match the directory name in your `fern/apis/` folder. @@ -79,7 +79,7 @@ Use the `--api` option to target a specific API. This is particularly useful whe fern generate --api payments-api ``` -## group +## Group Use the `--group` option to target a specific generator group. @@ -88,7 +88,7 @@ Use the `--group` option to target a specific generator group. fern generate --group ruby-sdk ``` -## version +## Version Use the `--version` option to specify the SDK version number, typically following semantic versioning (semver) format (`MAJOR.MINOR.PATCH`). This is particularly useful in CI/CD pipelines when publishing SDK releases. diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 300965eaa..36ee83d1d 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -115,7 +115,7 @@ navigation: contents: - link: Ask Fern href: /learn/ask-fern/getting-started/what-is-ask-fern - - page: MCP server for your site + - page: MCP Server for your site path: ./pages/ai/mcp-server.mdx slug: mcp-server - page: Fern Scribe (coming soon) @@ -199,7 +199,7 @@ navigation: contents: - page: Overview path: ./pages/authentication/overview.mdx - - page: Role based access control (RBAC) + - page: Role based access control (rbac) path: ./pages/authentication/rbac.mdx slug: rbac - page: Set up OAuth diff --git a/fern/products/docs/pages/api-references/api-explorer.mdx b/fern/products/docs/pages/api-references/api-explorer.mdx index 178828490..e431a1eb5 100644 --- a/fern/products/docs/pages/api-references/api-explorer.mdx +++ b/fern/products/docs/pages/api-references/api-explorer.mdx @@ -24,7 +24,7 @@ Allow users to test their calls in a sandbox environment or select the environme
-### WebSocket Playground +### WebSocket playground 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. diff --git a/fern/products/docs/pages/api-references/autopopulate-api-key.mdx b/fern/products/docs/pages/api-references/autopopulate-api-key.mdx index 59b66624d..e803da2c4 100644 --- a/fern/products/docs/pages/api-references/autopopulate-api-key.mdx +++ b/fern/products/docs/pages/api-references/autopopulate-api-key.mdx @@ -21,7 +21,7 @@ API key injection can work in two different ways depending on your company's aut -### How the JWT flow works +### How the jwt flow works 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: diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index efdb7b3f9..6a0741d34 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -11,7 +11,7 @@ If you are using an OpenAPI Specification, sections are created based on the `ta If you would like to only display a subset of endpoints, read more about the Audiences property for [OpenAPI Specifications](/learn/api-definitions/openapi/extensions/audiences) or [Fern Definitions](/learn/api-definition/fern/audiences). -## Ordering the API Reference +## Ordering the API reference ### Alphabetizing endpoints and sections To sort all sections and endpoints alphabetically, unless explicitly ordered in `layout`, set `alphabetized` to `true`. @@ -94,7 +94,7 @@ To reference an endpoint, you can use either: Content ordered in the API Reference -## Customizing the API Reference +## Customizing the API reference ### Renaming sections diff --git a/fern/products/docs/pages/api-references/endpoint-errors.mdx b/fern/products/docs/pages/api-references/endpoint-errors.mdx index 1eb559b9c..33ba3ec0c 100644 --- a/fern/products/docs/pages/api-references/endpoint-errors.mdx +++ b/fern/products/docs/pages/api-references/endpoint-errors.mdx @@ -15,7 +15,7 @@ navigation: ``` -## Example +## Example ![Endpoint errors](https://fern-image-hosting.s3.amazonaws.com/fern/errors.png) diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 5b6d3fd1f..79e5fa62a 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -1,84 +1,84 @@ ---- -title: Generate your API Reference -description: Use Fern Docs to generate your API Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. ---- - -A key benefit of using Fern Docs is that once you've defined your API, you get your API Reference documentation with just one line. -Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types, -and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). - -Example: - -```yml docs.yml -navigation: - - api: API Reference -``` - -### API Reference configuration options - -| Property | Value | -| ---------------- | ------------------------------------------------------------------------------------------------------- | -| `api` (required) | Title of the API Reference Section | -| `api-name` | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference) | -| `audiences` | List of [audiences](/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference | -| `availability` | Set the [availability status](/learn/docs/api-references/customize-api-reference-layout#adding-availability) for the entire API Reference or specific sections | -| `display-errors` | Displays error schemas in the API References | -| `summary` | Relative path to the Markdown file; the summary is displayed at the top of the API section | -| `layout` | Customize the order that your API endpoints are displayed in the docs site | -| `icon` | Icon to display next to the API section in the navigation | -| `slug` | Customize the slug for the API section (by default, the slug is generated from the API title) | -| `skip-slug` | When `true`, skips the slug generation for the API section | -| `alphabetized` | When `true`, organizes all sections and endpoints in alphabetical order | -| `flattened` | Display all endpoints at the top level (hides the API Reference Section's title) | -| `paginated` | Display all endpoints on separate pages (by default, endpoints are displayed on one single, long page) | - -More on customizing your API Reference [here](/learn/docs/api-references/customize-api-reference-layout). - -### Include more than one API Reference - -To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed. - -For example, your file structure might look like this: - -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ plant-api/ - │ └─ api.yml # API definition - └─ garden-api/ - └─ api.yml # API definition -``` - -For a simple setup without tabs, you can include multiple API references directly in your navigation: - -```yaml title="docs.yml" -navigation: - - api: Plant Store - api-name: plant-api # Matches folder name containing your API definition - - api: Garden - api-name: garden-api # Matches folder name containing your API definition -``` - -When using tabs, each API reference must be placed within a tab's `layout`: - -```yaml title="docs.yml" {12, 17} -tabs: - plant-api: - display-name: Plant Store API - icon: leaf - garden-api: - display-name: Garden API - icon: tree -navigation: - - tab: plant-api # References the tab defined above - layout: - - api: Plant Store API - api-name: plant-api # Matches folder name containing your API definition - skip-slug: true - - tab: garden-api # References the tab defined above - layout: - - api: Garden API - api-name: garden-api # Matches folder name containing your API definition - skip-slug: true -``` +--- +title: Generate your API Reference +description: Use Fern Docs to generate your API Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. +--- + +A key benefit of using Fern Docs is that once you've defined your API, you get your API Reference documentation with just one line. +Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types, +and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). + +Example: + +```yml docs.yml +navigation: + - api: API Reference +``` + +### API reference configuration options + +| Property | Value | +| ---------------- | ------------------------------------------------------------------------------------------------------- | +| `api` (required) | Title of the API Reference Section | +| `api-name` | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference) | +| `audiences` | List of [audiences](/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference | +| `availability` | Set the [availability status](/learn/docs/api-references/customize-api-reference-layout#adding-availability) for the entire API Reference or specific sections | +| `display-errors` | Displays error schemas in the API References | +| `summary` | Relative path to the Markdown file; the summary is displayed at the top of the API section | +| `layout` | Customize the order that your API endpoints are displayed in the docs site | +| `icon` | Icon to display next to the API section in the navigation | +| `slug` | Customize the slug for the API section (by default, the slug is generated from the API title) | +| `skip-slug` | When `true`, skips the slug generation for the API section | +| `alphabetized` | When `true`, organizes all sections and endpoints in alphabetical order | +| `flattened` | Display all endpoints at the top level (hides the API Reference Section's title) | +| `paginated` | Display all endpoints on separate pages (by default, endpoints are displayed on one single, long page) | + +More on customizing your API Reference [here](/learn/docs/api-references/customize-api-reference-layout). + +### Include more than one API reference + +To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed. + +For example, your file structure might look like this: + +```bash +fern/ + ├─ fern.config.json + ├─ docs.yml + ├─ plant-api/ + │ └─ api.yml # API definition + └─ garden-api/ + └─ api.yml # API definition +``` + +For a simple setup without tabs, you can include multiple API references directly in your navigation: + +```yaml title="docs.yml" +navigation: + - api: Plant Store + api-name: plant-api # Matches folder name containing your API definition + - api: Garden + api-name: garden-api # Matches folder name containing your API definition +``` + +When using tabs, each API reference must be placed within a tab's `layout`: + +```yaml title="docs.yml" {12, 17} +tabs: + plant-api: + display-name: Plant Store API + icon: leaf + garden-api: + display-name: Garden API + icon: tree +navigation: + - tab: plant-api # References the tab defined above + layout: + - api: Plant Store API + api-name: plant-api # Matches folder name containing your API definition + skip-slug: true + - tab: garden-api # References the tab defined above + layout: + - api: Garden API + api-name: garden-api # Matches folder name containing your API definition + skip-slug: true +``` diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index 037d7f3b9..a9844880f 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -9,7 +9,7 @@ Fern enables you to generate professional, interactive API reference documentati Alchemy's OpenRPC API Reference Example -## How to Add an OpenRPC Endpoint +## How to add an OpenRPC endpoint 1. Add your OpenRPC specification file (e.g., `openrpc.yaml`) to your `/fern` directory. 2. Configure your `generators.yml` to point to your OpenRPC spec: @@ -22,13 +22,13 @@ Fern enables you to generate professional, interactive API reference documentati ``` -### Configuration Properties +### Configuration properties Path to your OpenRPC specification file. You can include multiple OpenRPC specs if your project exposes more than one JSON-RPC API. -## Common Use Cases +## Common use cases JSON-RPC APIs are widely used for: - **Blockchain & Crypto**: Node RPC endpoints, wallet APIs diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index a968e3241..69d8dce94 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -1,134 +1,134 @@ ---- -title: Generate your webhook reference -description: Use Fern Docs to generate your webhook reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. ---- - -Similar to API References, Fern Docs can automatically generate your webhook reference documentation from your API definition. - -Fern supports webhooks through: -- **OpenAPI 3.1+**: Use the native `webhooks` field with an `operationId` (recommended) -- **OpenAPI 3.0**: Use the `x-fern-webhook: true` extension -- **Fern Definition**: Define `webhooks` in your specification - -For more information on how to define webhooks, see: -- [Webhooks in OpenAPI](../../openapi-definition/endpoints/webhooks) -- [Webhooks in Fern Definition](../../fern-definition/webhooks) - -## Configure your webhook reference - -Add a page title (`api`) and reference the name of the directory where your where your webhook definition is located (`api-name`). - -```yml docs.yml {11-12} -navigation: - - section: Introduction - contents: - - page: Getting Started - path: ../introduction/getting-started.md - - page: Authentication - path: ../introduction/authentication.md - - api: API Reference - api-name: api-v1 - display-errors: true - - api: Webhook Reference - api-name: webhooks-v1 -``` - -For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). - -### Directory structure -Your webhooks should be defined in a dedicated folder within your Fern project: - - - -```bash -fern/ - └── apis/ - ├── webhooks-v1/ # Webhook definition - │ ├── openapi/ - │ │ └── openapi.yml - │ └── generators.yml - └── api-v1/ # Regular API endpoints -``` - -If you're using OpenAPI, your `generators.yml` file should point to your OpenAPI specification: - -```yml generators.yml -api: - path: openapi/openapi.yml -``` - -You can read more about how to define webhooks in your OpenAPI specification [here](/learn/api-definitions/openapi/endpoints/webhooks). - - -```bash -fern/ - └── apis/ - ├── webhooks-v1/ # Webhook definition - │ ├── definition/ - │ │ ├── api.yml - │ │ └── webhooks.yml - │ └── generators.yml - └── api-v1/ # Regular API endpoints -``` - -You can read more about how to define webhooks in your Fern Definition [here](/learn/api-definition/fern/webhooks). - - - -### Include more than one webhook reference -To include multiple webhook definitions in your documentation, use the `api-name` property: - -```yaml title="docs.yml" -navigation: - - api: Payment Webhooks - api-name: payment-webhooks - - api: Order Webhooks - api-name: order-webhooks -``` - -When using multiple webhook definitions, organize them in separate directories within your Fern project: - -```bash -fern/ - └── apis/ - ├── payment-webhooks/ # Payment webhook definitions - │ ├── openapi/ - │ │ └── openapi.yml # Payment webhook OpenAPI spec - │ └── generators.yml - └── order-webhooks/ # Order webhook definitions - ├── openapi/ - │ └── openapi.yml # Order webhook OpenAPI spec - └── generators.yml -``` - -### Create individual documentation pages for each webhook event - -To display each webhook event as an individual page with rich examples: - - - -Reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: -- `{tag}` is the first tag (lowercase) from your webhook definition -- `{webhook-event-name}` is the `operationId` from your webhook definition - -```yaml title="docs.yml" -navigation: - - subpackage_plants.newPlantWebhook -``` - - - For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks). - - - - -Reference the individual webhook event using the `subpackage_{name}.{webhook-event-name}` format, where: -- `{name}` is the name of your API as defined in the `api.yml` file for your webhook definition. -- `{webhook-event-name}` is the identifier from your webhook definition - -```yaml title="docs.yml" -navigation: - - subpackage_api.newPlantWebhook -``` - - +--- +title: Generate your webhook reference +description: Use Fern Docs to generate your webhook reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. +--- + +Similar to API References, Fern Docs can automatically generate your webhook reference documentation from your API definition. + +Fern supports webhooks through: +- **OpenAPI 3.1+**: Use the native `webhooks` field with an `operationId` (recommended) +- **OpenAPI 3.0**: Use the `x-fern-webhook: true` extension +- **Fern Definition**: Define `webhooks` in your specification + +For more information on how to define webhooks, see: +- [Webhooks in OpenAPI](../../openapi-definition/endpoints/webhooks) +- [Webhooks in Fern Definition](../../fern-definition/webhooks) + +## Configure your Webhook reference + +Add a page title (`api`) and reference the name of the directory where your where your webhook definition is located (`api-name`). + +```yml docs.yml {11-12} +navigation: + - section: Introduction + contents: + - page: Getting Started + path: ../introduction/getting-started.md + - page: Authentication + path: ../introduction/authentication.md + - api: API Reference + api-name: api-v1 + display-errors: true + - api: Webhook Reference + api-name: webhooks-v1 +``` + +For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). + +### Directory structure +Your webhooks should be defined in a dedicated folder within your Fern project: + + + +```bash +fern/ + └── apis/ + ├── webhooks-v1/ # Webhook definition + │ ├── openapi/ + │ │ └── openapi.yml + │ └── generators.yml + └── api-v1/ # Regular API endpoints +``` + +If you're using OpenAPI, your `generators.yml` file should point to your OpenAPI specification: + +```yml generators.yml +api: + path: openapi/openapi.yml +``` + +You can read more about how to define webhooks in your OpenAPI specification [here](/learn/api-definitions/openapi/endpoints/webhooks). + + +```bash +fern/ + └── apis/ + ├── webhooks-v1/ # Webhook definition + │ ├── definition/ + │ │ ├── api.yml + │ │ └── webhooks.yml + │ └── generators.yml + └── api-v1/ # Regular API endpoints +``` + +You can read more about how to define webhooks in your Fern Definition [here](/learn/api-definition/fern/webhooks). + + + +### Include more than one Webhook reference +To include multiple webhook definitions in your documentation, use the `api-name` property: + +```yaml title="docs.yml" +navigation: + - api: Payment Webhooks + api-name: payment-webhooks + - api: Order Webhooks + api-name: order-webhooks +``` + +When using multiple webhook definitions, organize them in separate directories within your Fern project: + +```bash +fern/ + └── apis/ + ├── payment-webhooks/ # Payment webhook definitions + │ ├── openapi/ + │ │ └── openapi.yml # Payment webhook OpenAPI spec + │ └── generators.yml + └── order-webhooks/ # Order webhook definitions + ├── openapi/ + │ └── openapi.yml # Order webhook OpenAPI spec + └── generators.yml +``` + +### Create individual documentation pages for each Webhook event + +To display each webhook event as an individual page with rich examples: + + + +Reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: +- `{tag}` is the first tag (lowercase) from your webhook definition +- `{webhook-event-name}` is the `operationId` from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_plants.newPlantWebhook +``` + + + For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks). + + + + +Reference the individual webhook event using the `subpackage_{name}.{webhook-event-name}` format, where: +- `{name}` is the name of your API as defined in the `api.yml` file for your webhook definition. +- `{webhook-event-name}` is the identifier from your webhook definition + +```yaml title="docs.yml" +navigation: + - subpackage_api.newPlantWebhook +``` + + diff --git a/fern/products/docs/pages/api-references/http-snippets.mdx b/fern/products/docs/pages/api-references/http-snippets.mdx index 35a8a6447..b9ed30319 100644 --- a/fern/products/docs/pages/api-references/http-snippets.mdx +++ b/fern/products/docs/pages/api-references/http-snippets.mdx @@ -31,15 +31,15 @@ settings: ``` -## How It Works +## How it works -### Request Examples +### Request examples To generate HTTP snippets, add request examples to your API definition: - For Fern Definition: Follow the [examples documentation](/learn/api-definition/fern/examples) - For OpenAPI: Follow the [request/response examples documentation](/learn/api-definition/openapi/extensions/others#request--response-examples) -### Set Default Snippet Language +### Set default snippet language HTTP snippets support several languages. Our development work is driven by customer requests, so please request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose). @@ -66,7 +66,7 @@ navigation: ``` -### Generated Features +### Generated features HTTP snippets automatically include: - Authentication headers with placeholders (e.g., ``) @@ -75,7 +75,7 @@ HTTP snippets automatically include: - Error handling patterns - SSL/TLS configuration where applicable -### Display Behavior +### Display behavior - If your API has SDK snippets, those will be shown by default - If no SDK snippets exist, HTTP snippets will display automatically diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 0d9845025..7084d2ace 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -15,7 +15,7 @@ description: Enable SDK code examples in TypeScript, Python, Go, and more from t ![SDK code snippet selector](https://fern-image-hosting.s3.amazonaws.com/sdk-code-snippets.png) -## Configuring SDK Snippets +## Configuring SDK snippets To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and then reference that name in `docs.yml`. @@ -25,7 +25,7 @@ To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and In order to generate code snippets, Fern needs to read request examples from your API definition. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/). -### Define a package name for your SDK(s) +### Define a package name for your sdk(s) Configure package names in your `generators.yml` file: * For **Python, TypeScript, Ruby, and .NET/C#**, add `package-name: your-package-name` to the `output` section. diff --git a/fern/products/docs/pages/api-references/server-urls.mdx b/fern/products/docs/pages/api-references/server-urls.mdx index e7387e4e9..8f315d5f9 100644 --- a/fern/products/docs/pages/api-references/server-urls.mdx +++ b/fern/products/docs/pages/api-references/server-urls.mdx @@ -13,7 +13,7 @@ You can configure multiple server URLs in your API definition using either Fern - [Configure servers in OpenAPI](/learn/api-definition/openapi/extensions/others#server-names) - [Configure environments in Fern Definition](/learn/api-definition/fern/api-yml/environments) -## User Interface +## User interface When multiple servers are configured, users will see a dropdown menu in the API Reference that allows them to switch between environments: @@ -45,7 +45,7 @@ Here's an example of the [Flagright docs site](https://docs.flagright.com/framl- -## Environment Persistence +## Environment persistence When you select an environment, it's reflected across the entire API Reference - both in the displayed URLs and in the [API Explorer](/learn/docs/api-references/api-explorer). This selection persists as you navigate between different pages. diff --git a/fern/products/docs/pages/component-library/custom-components/conditional-rendering.mdx b/fern/products/docs/pages/component-library/custom-components/conditional-rendering.mdx index fd0f00c4e..1fe287e08 100644 --- a/fern/products/docs/pages/component-library/custom-components/conditional-rendering.mdx +++ b/fern/products/docs/pages/component-library/custom-components/conditional-rendering.mdx @@ -4,7 +4,7 @@ title: Conditionally Rendered Content You can conditionally render content based on the instance or version of the docs, in addition to the role of an authenticated user. -## Conditionally render content +## Conditionally render content ### Between instances diff --git a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx index 2bc5dabb8..cf316f65c 100644 --- a/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx +++ b/fern/products/docs/pages/component-library/custom-components/custom-react-components.mdx @@ -59,7 +59,7 @@ import { CustomCard } from "../components/CustomCard" ``` -## Why not just use custom CSS and JS instead? +## Why not just use custom CSS and JS instead? While you can bundle React components as custom JavaScript, using Fern's built-in React component support provides several key advantages: diff --git a/fern/products/docs/pages/component-library/default-components/accordion-groups.mdx b/fern/products/docs/pages/component-library/default-components/accordion-groups.mdx index b977489ae..21ad6222e 100644 --- a/fern/products/docs/pages/component-library/default-components/accordion-groups.mdx +++ b/fern/products/docs/pages/component-library/default-components/accordion-groups.mdx @@ -30,11 +30,11 @@ Accordion Groups allow you to organize content into collapsible sections, making -### Enhanced Search Functionality +### Enhanced search functionality The recent update to our Accordion component improves content discoverability by allowing users to search through all content, including collapsed sections, using the browser's search function (Cmd+F / Ctrl+F). -### Usage Examples +### Usage examples Here are some examples of how to use the Accordion Group component: diff --git a/fern/products/docs/pages/component-library/default-components/badges.mdx b/fern/products/docs/pages/component-library/default-components/badges.mdx index e08ba9f4b..0227f91a4 100644 --- a/fern/products/docs/pages/component-library/default-components/badges.mdx +++ b/fern/products/docs/pages/component-library/default-components/badges.mdx @@ -10,7 +10,7 @@ To display longer notes, use the [Callouts component](/docs/writing-content/comp -### Plant Care API v2.1.0 New +### Plant care API v2.1.0 new diff --git a/fern/products/docs/pages/component-library/default-components/callouts.mdx b/fern/products/docs/pages/component-library/default-components/callouts.mdx index 4a87a2eb7..75993b824 100644 --- a/fern/products/docs/pages/component-library/default-components/callouts.mdx +++ b/fern/products/docs/pages/component-library/default-components/callouts.mdx @@ -9,7 +9,7 @@ To display very short pieces of information like status indicators and version n ## Callout varieties -### Note callouts +### Note Callouts This adds a note in the content @@ -17,7 +17,7 @@ To display very short pieces of information like status indicators and version n This adds a note in the content ``` -### Warning callouts +### Warning Callouts This raises a warning to watch out for @@ -25,7 +25,7 @@ To display very short pieces of information like status indicators and version n This raises a warning to watch out for ``` -### Success callouts +### Success Callouts This indicates a successful operation or positive outcome @@ -33,7 +33,7 @@ To display very short pieces of information like status indicators and version n This indicates a successful operation or positive outcome ``` -### Error callouts +### Error Callouts This indicates a potential error @@ -41,7 +41,7 @@ To display very short pieces of information like status indicators and version n This indicates a potential error ``` -### Info callouts +### Info Callouts This draws attention to important information @@ -49,7 +49,7 @@ To display very short pieces of information like status indicators and version n This draws attention to important information ``` -### Launch callouts +### Launch Callouts This celebrates a product launch or other announcement @@ -58,7 +58,7 @@ To display very short pieces of information like status indicators and version n ``` -### Tip callouts +### Tip Callouts This suggests a helpful tip @@ -66,7 +66,7 @@ To display very short pieces of information like status indicators and version n This suggests a helpful tip ``` -### Check callouts +### Check Callouts This brings us a checked status diff --git a/fern/products/docs/pages/component-library/default-components/embed.mdx b/fern/products/docs/pages/component-library/default-components/embed.mdx index fa7aaa40b..06bc898f4 100644 --- a/fern/products/docs/pages/component-library/default-components/embed.mdx +++ b/fern/products/docs/pages/component-library/default-components/embed.mdx @@ -28,7 +28,7 @@ Fern also implements a custom component for embedding downloadable assets: ## Examples -### Video File +### Video file @@ -57,7 +57,7 @@ Fern also implements a custom component for embedding downloadable assets: -### PDF Document +### Pdf document @@ -65,7 +65,7 @@ Fern also implements a custom component for embedding downloadable assets: ``` -## Common MIME Types +## Common mime types | File Type | MIME Type | | ---------- | ----------------- | @@ -81,7 +81,7 @@ Fern also implements a custom component for embedding downloadable assets: video files, consider using MP4 format for maximum compatibility. -## Downloadable Assets +## Downloadable assets Enable users to download assets from within your documentation, instead of linking to them, by using the `` component. diff --git a/fern/products/docs/pages/component-library/default-components/icons.mdx b/fern/products/docs/pages/component-library/default-components/icons.mdx index 95c07f753..5ce7da828 100644 --- a/fern/products/docs/pages/component-library/default-components/icons.mdx +++ b/fern/products/docs/pages/component-library/default-components/icons.mdx @@ -36,7 +36,7 @@ Add Font Awesome icons to your docs with customizable styles, colors and sizes u Size in 0.25rem increments (e.g., 4 = 1rem) -## Font Awesome Styles +## Font awesome styles You can use any Font Awesome style by using either: - Short syntax: `icon="heart"` (defaults to solid) @@ -69,7 +69,7 @@ You can use any Font Awesome style by using either: -## Best Practices +## Best practices - Use icons consistently throughout your documentation - Keep icon sizes appropriate for their context (16-24px for inline, larger for featured items) diff --git a/fern/products/docs/pages/component-library/default-components/steps.mdx b/fern/products/docs/pages/component-library/default-components/steps.mdx index 60156a695..9a0933857 100644 --- a/fern/products/docs/pages/component-library/default-components/steps.mdx +++ b/fern/products/docs/pages/component-library/default-components/steps.mdx @@ -61,13 +61,13 @@ The Steps component helps organize sequential content with automatic numbering, ## Properties -### Steps Properties +### Steps properties Whether to include the steps in the table of contents. Defaults to `false`. -### Step Properties +### Step properties Optional title for the step diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx index 4b0046cd5..45348b7a2 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown.mdx @@ -177,7 +177,7 @@ Common video attributes: For more details about the HTML video element and its attributes, see the [MDN documentation on the video element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video). -## Embed YouTube or Loom videos +## Embed youtube or loom videos You can embed videos from YouTube, Loom, Vimeo, and other streaming platforms using an `