Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .vale/styles/FernStyles/Headings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
6 changes: 3 additions & 3 deletions fern/products/api-def/asyncapi-pages/auth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`:

Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion fern/products/api-def/asyncapi-pages/automation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ api:
version: 0.8.8
```

### From Git repository
### From git repository
```yaml title="generators.yml" {3-7}
api:
specs:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions fern/products/api-def/ferndef-pages/types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
12 changes: 6 additions & 6 deletions fern/products/api-def/grpc-pages/auth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -226,7 +226,7 @@ class ApiKeyAuthInterceptor(grpc.ServerInterceptor):
return continuation(handler_call_details)
```

## OAuth2 Integration
## OAuth2 integration

Integrate with OAuth2 providers:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
gRPC's flexible authentication system allows you to implement secure, scalable authentication patterns that work across different environments and use cases.
6 changes: 3 additions & 3 deletions fern/products/api-def/grpc-pages/automation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
```

## Protocol Buffer validation
## Protocol buffer validation

Add validation steps for your Protocol Buffer files:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
This ensures that any changes to your gRPC services are automatically reflected in your SDKs and documentation, maintaining consistency across your entire API ecosystem.
18 changes: 9 additions & 9 deletions fern/products/api-def/grpc-pages/servers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

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:

Expand Down Expand Up @@ -41,7 +41,7 @@
server.wait_for_termination()
```

## TLS Configuration
## TLS configuration

Check warning on line 44 in fern/products/api-def/grpc-pages/servers.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [FernStyles.Acronyms] 'TLS' has no definition. Raw Output: {"message": "[FernStyles.Acronyms] 'TLS' has no definition.", "location": {"path": "fern/products/api-def/grpc-pages/servers.mdx", "range": {"start": {"line": 44, "column": 4}}}, "severity": "INFO"}

Configure TLS for secure production deployments:

Expand Down Expand Up @@ -78,7 +78,7 @@
return server
```

## Server Options
## Server options

Configure various server options for performance and behavior:

Expand Down Expand Up @@ -111,7 +111,7 @@
return server
```

## Health Checking
## Health checking

Implement health checking for load balancer integration:

Expand Down Expand Up @@ -208,7 +208,7 @@
return server
```

## Load Balancing
## Load balancing

Configure client-side load balancing:

Expand Down Expand Up @@ -244,7 +244,7 @@
return channel
```

## Kubernetes Deployment
## Kubernetes deployment

Deploy gRPC services on Kubernetes:

Expand Down Expand Up @@ -295,7 +295,7 @@
type: ClusterIP
```

## Monitoring and Observability
## Monitoring and observability

Add monitoring and tracing to your gRPC server:

Expand Down Expand Up @@ -354,7 +354,7 @@
return server
```

## Environment-specific Configuration
## Environment-specific configuration

Configure servers for different environments:

Expand Down Expand Up @@ -424,4 +424,4 @@
return server
```

Proper server configuration ensures your gRPC services are secure, performant, and ready for production workloads.
Proper server configuration ensures your gRPC services are secure, performant, and ready for production workloads.
10 changes: 5 additions & 5 deletions fern/products/api-def/grpc-pages/services/errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ enum ErrorCode {
}
```

## Standard Error Handling
## Standard error handling

Implement standard gRPC error responses:

Expand Down Expand Up @@ -202,7 +202,7 @@ class ErrorDemoServiceServicer(errors_pb2_grpc.ErrorDemoServiceServicer):
])
```

## Custom Error Types
## Custom error types

Define custom error types for domain-specific errors:

Expand Down Expand Up @@ -342,7 +342,7 @@ class UserService(user_pb2_grpc.UserServiceServicer):
# Continue with user creation...
```

## Error Interceptors
## Error interceptors

Implement global error handling with interceptors:

Expand Down Expand Up @@ -404,7 +404,7 @@ class ErrorInterceptor(grpc.ServerInterceptor):
return None
```

## Client-side Error Handling
## Client-side error handling

Handle errors on the client side:

Expand Down Expand Up @@ -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:

Expand Down
14 changes: 7 additions & 7 deletions fern/products/api-def/grpc-pages/services/grpc-services.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -79,7 +79,7 @@ enum ThemeMode {
}
```

## Request and Response Messages
## Request and response messages

Define clear request and response message types:

Expand Down Expand Up @@ -147,7 +147,7 @@ message SearchMetadata {
}
```

## Service Implementation
## Service implementation

Implement the service in your preferred language:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:

Expand Down
Loading