From ccdc3c7cf089ddc6cc751bd8837420360ae0c3e7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 14 Aug 2025 15:58:20 -0400 Subject: [PATCH] add notes about language support to api def overview pages --- .../api-def/asyncapi-pages/overview.mdx | 12 +++-- .../api-def/ferndef-pages/overview.mdx | 2 +- fern/products/api-def/grpc-pages/overview.mdx | 53 +++---------------- .../api-def/openapi-pages/overview.mdx | 6 +-- .../api-def/openrpc-pages/overview.mdx | 8 +-- 5 files changed, 24 insertions(+), 57 deletions(-) diff --git a/fern/products/api-def/asyncapi-pages/overview.mdx b/fern/products/api-def/asyncapi-pages/overview.mdx index e11337086..c3cecacad 100644 --- a/fern/products/api-def/asyncapi-pages/overview.mdx +++ b/fern/products/api-def/asyncapi-pages/overview.mdx @@ -1,14 +1,16 @@ --- title: What is an AsyncAPI Specification? -subtitle: AsyncAPI is a standard for documenting event-driven APIs +description: AsyncAPI is a standard for documenting event-driven APIs --- + + Fern only supports AsyncAPI SDK generation for TypeScript and Python. + + The AsyncAPI Specification is a framework used by developers to document event-driven APIs. The specification is written in JSON or YAML and contains all of your channels, messages, schemas, and authentication schemes. Fern is compatible with AsyncAPI specification [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) and [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0). - 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) - Below is an example of an AsyncAPI file: ```yaml asyncapi.yml @@ -107,7 +109,9 @@ components: - message ``` -## Setup 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) Start by initializing your fern folder with an AsyncAPI spec diff --git a/fern/products/api-def/ferndef-pages/overview.mdx b/fern/products/api-def/ferndef-pages/overview.mdx index 25b04a2db..be9f27980 100644 --- a/fern/products/api-def/ferndef-pages/overview.mdx +++ b/fern/products/api-def/ferndef-pages/overview.mdx @@ -1,6 +1,6 @@ --- title: What is a Fern Definition? -subtitle: "A Fern Definition is a set of YAML files that describe your API." +description: "A Fern Definition is a set of YAML files that describe your API." --- A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo, diff --git a/fern/products/api-def/grpc-pages/overview.mdx b/fern/products/api-def/grpc-pages/overview.mdx index a25da7a3c..634cff600 100644 --- a/fern/products/api-def/grpc-pages/overview.mdx +++ b/fern/products/api-def/grpc-pages/overview.mdx @@ -1,13 +1,15 @@ --- title: What is gRPC? -subtitle: gRPC is a high-performance RPC framework that uses Protocol Buffers +description: gRPC is a high-performance RPC framework that uses Protocol Buffers --- + + Fern only supports gRPC SDK generation for .NET/C#. + + gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. It uses Protocol Buffers (protobuf) as the interface definition language and supports multiple programming languages. Fern is compatible with gRPC services and can generate SDKs and documentation from your `.proto` files. - 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) - Below is an example of a gRPC service definition: ```protobuf user_service.proto @@ -155,27 +157,10 @@ enum ChatMessageType { } ``` -## gRPC Features - -gRPC offers several key features that make it ideal for modern applications: +## Set up your fern folder -### High Performance -- Binary protocol with Protocol Buffers -- HTTP/2 transport for multiplexing and flow control -- Efficient serialization and deserialization - -### Multiple Communication Patterns -- **Unary RPCs**: Simple request/response -- **Server Streaming**: Server sends stream of responses -- **Client Streaming**: Client sends stream of requests -- **Bidirectional Streaming**: Both sides send streams - -### Cross-Platform Support -- Native support for 10+ programming languages -- Generated client libraries and server stubs -- Consistent API across all platforms + 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) -## Setup your fern folder Start by initializing your fern folder with a gRPC service @@ -196,26 +181,4 @@ fern/ └─ proto/ ├─ user_service.proto └─ common.proto -``` - -## gRPC vs REST - -| Feature | gRPC | REST | -|---------|------|------| -| Protocol | HTTP/2 | HTTP/1.1 | -| Data Format | Protocol Buffers | JSON | -| Performance | High | Moderate | -| Streaming | Native support | Limited | -| Browser Support | Limited | Full | -| Schema | Strongly typed | Flexible | -| Code Generation | Built-in | Third-party tools | - -## Common Use Cases - -gRPC is particularly well-suited for: - -- **Microservices Communication**: High-performance inter-service communication -- **Real-time Applications**: Streaming for live updates and real-time features -- **Mobile Applications**: Efficient mobile-to-server communication -- **IoT Systems**: Lightweight communication for resource-constrained devices -- **APIs with Strong Contracts**: Type-safe communication with schema evolution \ No newline at end of file +``` \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/overview.mdx b/fern/products/api-def/openapi-pages/overview.mdx index c6cc053e0..d58c7ed21 100644 --- a/fern/products/api-def/openapi-pages/overview.mdx +++ b/fern/products/api-def/openapi-pages/overview.mdx @@ -1,14 +1,12 @@ --- title: What is an OpenAPI Specification? -subtitle: OpenAPI is a standard for documenting REST APIs +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 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). - 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) - Below is an example of an OpenAPI file: ```yaml openapi.yml @@ -106,6 +104,8 @@ components: ## Setup 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 diff --git a/fern/products/api-def/openrpc-pages/overview.mdx b/fern/products/api-def/openrpc-pages/overview.mdx index 17341b14b..cb9a03cb3 100644 --- a/fern/products/api-def/openrpc-pages/overview.mdx +++ b/fern/products/api-def/openrpc-pages/overview.mdx @@ -1,14 +1,12 @@ --- title: What is an OpenRPC Specification? -subtitle: OpenRPC is a standard for documenting JSON-RPC APIs +description: OpenRPC is a standard for documenting JSON-RPC APIs --- The OpenRPC Specification is a framework used by developers to document JSON-RPC APIs. The specification is written in JSON or YAML and contains all of your methods, parameters, schemas, and server configurations. Fern is compatible with OpenRPC specification [v1.3.2](https://spec.open-rpc.org/) and [v1.2.6](https://github.com/open-rpc/spec/releases/tag/1.2.6). - 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) - Below is an example of an OpenRPC file: ```yaml openrpc.yml @@ -144,7 +142,9 @@ components: - timestamp ``` -## Setup 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) Start by initializing your fern folder with an OpenRPC spec