From 73f4f4834018b586b5977816018bd798ed7bfea5 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 24 Oct 2025 17:55:45 +0000 Subject: [PATCH 1/2] Convert API definitions section headings to sentence case - Updated all headings in API definitions section to use sentence case - Added new Vale exceptions for technical terms (OpenAPI, AsyncAPI, TLS, JWT, OAuth2, etc.) - Fixed headings in gRPC, OpenAPI, AsyncAPI, OpenRPC, and Fern Definition pages - Preserved proper nouns and Vale exceptions as specified Co-Authored-By: Devin Logan --- .vale/styles/FernStyles/Headings.yml | 29 +++++++++++++++++++ fern/products/api-def/asyncapi-pages/auth.mdx | 6 ++-- .../api-def/asyncapi-pages/automation.mdx | 2 +- .../ferndef-pages/endpoints/multipart.mdx | 2 +- fern/products/api-def/ferndef-pages/types.mdx | 4 +-- fern/products/api-def/grpc-pages/auth.mdx | 12 ++++---- .../api-def/grpc-pages/automation.mdx | 6 ++-- fern/products/api-def/grpc-pages/servers.mdx | 18 ++++++------ .../api-def/grpc-pages/services/errors.mdx | 10 +++---- .../grpc-pages/services/grpc-services.mdx | 14 ++++----- .../api-def/grpc-pages/services/streaming.mdx | 16 +++++----- .../openapi-pages/endpoints/multipart.mdx | 2 +- .../api-def/openapi-pages/servers.mdx | 2 +- fern/products/api-def/openrpc-pages/auth.mdx | 18 ++++++------ .../api-def/openrpc-pages/automation.mdx | 2 +- .../api-def/openrpc-pages/servers.mdx | 6 ++-- fern/products/api-def/pages/overrides.mdx | 2 +- 17 files changed, 90 insertions(+), 61 deletions(-) diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 6cf6d35cf..6ff529943 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -80,3 +80,32 @@ exceptions: - CSS - HTML - JSON + - OpenAPI + - AsyncAPI + - Fern Definition + - WebSockets + - MQTT + - JSON-RPC + - Protocol Buffers + - TLS + - JWT + - OAuth2 + - API + - CircleCI + - GitLab CI + - CI/CD + - Kubernetes + - Buf + - FastAPI + - PyPI + - Maven + - Spring Boot + - Pydantic + - Postman + - HTTP + - HTTPS + - TCP + - Protobuf + - Proto + - RBAC + - YAML diff --git a/fern/products/api-def/asyncapi-pages/auth.mdx b/fern/products/api-def/asyncapi-pages/auth.mdx index 8083f6001..f560bf3bd 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: diff --git a/fern/products/api-def/asyncapi-pages/automation.mdx b/fern/products/api-def/asyncapi-pages/automation.mdx index ffeb260cb..ae871c61d 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: 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/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/grpc-pages/auth.mdx b/fern/products/api-def/grpc-pages/auth.mdx index 81b27418e..40255773b 100644 --- a/fern/products/api-def/grpc-pages/auth.mdx +++ b/fern/products/api-def/grpc-pages/auth.mdx @@ -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: @@ -367,4 +367,4 @@ class RBACInterceptor(grpc.ServerInterceptor): return False ``` -gRPC's flexible authentication system allows you to implement secure, scalable authentication patterns that work across different environments and use cases. \ No newline at end of file +gRPC's flexible authentication system allows you to implement secure, scalable authentication patterns that work across different environments and use cases. \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/automation.mdx b/fern/products/api-def/grpc-pages/automation.mdx index 048c3b6b4..130906a6d 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: @@ -469,4 +469,4 @@ if __name__ == "__main__": sync_from_grpc_reflection("localhost:50051", "proto/") ``` -This ensures that any changes to your gRPC services are automatically reflected in your SDKs and documentation, maintaining consistency across your entire API ecosystem. \ No newline at end of file +This ensures that any changes to your gRPC services are automatically reflected in your SDKs and documentation, maintaining consistency across your entire API ecosystem. \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/servers.mdx b/fern/products/api-def/grpc-pages/servers.mdx index 3e1b6c41d..c01b4d66b 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: @@ -424,4 +424,4 @@ def create_server_from_config(config: ServerConfig): return server ``` -Proper server configuration ensures your gRPC services are secure, performant, and ready for production workloads. \ No newline at end of file +Proper server configuration ensures your gRPC services are secure, performant, and ready for production workloads. \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/services/errors.mdx b/fern/products/api-def/grpc-pages/services/errors.mdx index 91b3c15fd..a57974799 100644 --- a/fern/products/api-def/grpc-pages/services/errors.mdx +++ b/fern/products/api-def/grpc-pages/services/errors.mdx @@ -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..3dcc278c2 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: @@ -511,4 +511,4 @@ def stream_chat_client(): print(f"RPC failed: {e}") ``` -Streaming in gRPC enables powerful real-time applications while maintaining the benefits of strongly-typed contracts and efficient binary protocols. \ No newline at end of file +Streaming in gRPC enables powerful real-time applications while maintaining the benefits of strongly-typed contracts and efficient binary protocols. \ No newline at end of file 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/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/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..f10b176cc 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: diff --git a/fern/products/api-def/openrpc-pages/servers.mdx b/fern/products/api-def/openrpc-pages/servers.mdx index f00bf68c6..dd1442926 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 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. From f919c05a833c341152a384b1fe7959482ad102db Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 24 Oct 2025 18:16:49 +0000 Subject: [PATCH 2/2] Fix: Capitalize 'Docs' as it's a Fern product name Co-Authored-By: Devin Logan --- fern/products/api-def/pages/overrides.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/api-def/pages/overrides.mdx b/fern/products/api-def/pages/overrides.mdx index 8e4b2aa87..b1b03a590 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.