From 4903a7c5b55dc2aae0a246bb8c6cee312d012db8 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 14 Aug 2025 13:59:05 -0400 Subject: [PATCH 1/2] break up extensions into multiple pages, add redirects --- fern/docs.yml | 14 + fern/products/api-def/api-def.yml | 182 +++++--- .../extensions/availability.mdx | 17 + .../extensions/error-handling.mdx | 24 + .../asyncapi-pages/extensions/examples.mdx | 30 ++ .../asyncapi-pages/extensions/ignore.mdx | 24 + .../asyncapi-pages/extensions/others.mdx | 160 ------- .../asyncapi-pages/extensions/overview.md | 25 ++ .../asyncapi-pages/extensions/pagination.mdx | 19 + .../asyncapi-pages/extensions/retry.mdx | 19 + .../asyncapi-pages/extensions/server-name.mdx | 18 + .../asyncapi-pages/extensions/streaming.mdx | 17 + .../grpc-pages/extensions/availability.mdx | 30 ++ .../grpc-pages/extensions/base-path.mdx | 18 + .../grpc-pages/extensions/error-handling.mdx | 31 ++ .../grpc-pages/extensions/examples.mdx | 53 +++ .../api-def/grpc-pages/extensions/ignore.mdx | 35 ++ .../api-def/grpc-pages/extensions/others.mdx | 403 ----------------- .../api-def/grpc-pages/extensions/overview.md | 30 ++ .../grpc-pages/extensions/pagination.mdx | 36 ++ .../api-def/grpc-pages/extensions/retry.mdx | 33 ++ .../grpc-pages/extensions/sdk-group-name.mdx | 44 ++ .../grpc-pages/extensions/server-name.mdx | 20 + .../grpc-pages/extensions/streaming.mdx | 35 ++ .../api-def/grpc-pages/extensions/timeout.mdx | 28 ++ .../grpc-pages/extensions/union-naming.mdx | 22 + .../grpc-pages/extensions/validation.mdx | 36 ++ .../openapi-pages/extensions/api-version.mdx | 18 + .../openapi-pages/extensions/availability.mdx | 27 ++ .../openapi-pages/extensions/base-path.mdx | 18 + .../openapi-pages/extensions/enums.mdx | 57 +++ .../openapi-pages/extensions/examples.mdx | 65 +++ .../extensions/global-headers.mdx | 35 ++ .../openapi-pages/extensions/ignore.mdx | 26 ++ .../openapi-pages/extensions/others.mdx | 416 ------------------ .../openapi-pages/extensions/overview.md | 101 +++++ .../extensions/property-names.mdx | 19 + .../openapi-pages/extensions/schema-names.mdx | 82 ++++ .../openapi-pages/extensions/server-names.mdx | 25 ++ .../openrpc-pages/extensions/availability.mdx | 23 + .../openrpc-pages/extensions/base-path.mdx | 14 + .../extensions/error-handling.mdx | 31 ++ .../openrpc-pages/extensions/examples.mdx | 49 +++ .../openrpc-pages/extensions/ignore.mdx | 29 ++ .../openrpc-pages/extensions/others.mdx | 302 ------------- .../openrpc-pages/extensions/overview.md | 28 ++ .../openrpc-pages/extensions/pagination.mdx | 43 ++ .../openrpc-pages/extensions/retry.mdx | 25 ++ .../extensions/sdk-group-name.mdx | 35 ++ .../openrpc-pages/extensions/server-name.mdx | 18 + .../openrpc-pages/extensions/streaming.mdx | 26 ++ .../openrpc-pages/extensions/timeout.mdx | 23 + 52 files changed, 1606 insertions(+), 1332 deletions(-) create mode 100644 fern/products/api-def/asyncapi-pages/extensions/availability.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/error-handling.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/examples.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/ignore.mdx delete mode 100644 fern/products/api-def/asyncapi-pages/extensions/others.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/overview.md create mode 100644 fern/products/api-def/asyncapi-pages/extensions/pagination.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/retry.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/server-name.mdx create mode 100644 fern/products/api-def/asyncapi-pages/extensions/streaming.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/availability.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/base-path.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/error-handling.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/examples.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/ignore.mdx delete mode 100644 fern/products/api-def/grpc-pages/extensions/others.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/overview.md create mode 100644 fern/products/api-def/grpc-pages/extensions/pagination.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/retry.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/sdk-group-name.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/server-name.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/streaming.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/timeout.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/union-naming.mdx create mode 100644 fern/products/api-def/grpc-pages/extensions/validation.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/api-version.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/availability.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/base-path.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/enums.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/examples.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/global-headers.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/ignore.mdx delete mode 100644 fern/products/api-def/openapi-pages/extensions/others.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/overview.md create mode 100644 fern/products/api-def/openapi-pages/extensions/property-names.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/schema-names.mdx create mode 100644 fern/products/api-def/openapi-pages/extensions/server-names.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/availability.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/base-path.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/error-handling.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/examples.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/ignore.mdx delete mode 100644 fern/products/api-def/openrpc-pages/extensions/others.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/overview.md create mode 100644 fern/products/api-def/openrpc-pages/extensions/pagination.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/retry.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/sdk-group-name.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/server-name.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/streaming.mdx create mode 100644 fern/products/api-def/openrpc-pages/extensions/timeout.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 81c0430b1..3b8ea36c2 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -587,4 +587,18 @@ redirects: permanent: true - source: /learn/fern-definition/:slug* destination: /learn/api-definitions/ferndef/:slug* + permanent: true + + # Redirect old others.mdx extension pages to overview pages + - source: /learn/api-definitions/openapi/extensions/others + destination: /learn/api-definitions/openapi/extensions/overview + permanent: true + - source: /learn/api-definitions/asyncapi/extensions/others + destination: /learn/api-definitions/asyncapi/extensions/overview + permanent: true + - source: /learn/api-definitions/openrpc/extensions/others + destination: /learn/api-definitions/openrpc/extensions/overview + permanent: true + - source: /learn/api-definitions/grpc/extensions/others + destination: /learn/api-definitions/grpc/extensions/overview permanent: true \ No newline at end of file diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 0ba6c449c..509ddb0d6 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -1,9 +1,9 @@ navigation: - section: Overview contents: - - page: What is an API Definition? + - page: What is an API definition? path: ./pages/what-is-an-api-definition.mdx - - page: Project Structure + - page: Project structure path: ./pages/project-structure.mdx - section: OpenAPI collapsed: true @@ -18,38 +18,57 @@ navigation: - section: Endpoints slug: endpoints contents: - - page: HTTP JSON Endpoints + - page: HTTP JSON endpoints path: ./openapi-pages/endpoints/rest.mdx slug: http - page: Webhooks path: ./openapi-pages/webhooks.mdx - - page: Multipart Form Uploads + - 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 slug: extensions contents: + - page: Overview + path: ./openapi-pages/extensions/overview.md + - page: API version + path: ./openapi-pages/extensions/api-version.mdx - page: Audiences path: ./openapi-pages/extensions/audiences.mdx - - page: SDK Method Names + - page: Availability + path: ./openapi-pages/extensions/availability.mdx + - page: Base path + path: ./openapi-pages/extensions/base-path.mdx + - page: Enum descriptions and names + path: ./openapi-pages/extensions/enums.mdx + - page: Request + response examples + path: ./openapi-pages/extensions/examples.mdx + - page: Global headers + path: ./openapi-pages/extensions/global-headers.mdx + - page: Ignoring schemas or endpoints + path: ./openapi-pages/extensions/ignore.mdx + - page: SDK method names path: ./openapi-pages/extensions/method-names.mdx slug: method-names - - page: Parameter Names + - page: Parameter names path: ./openapi-pages/extensions/parameter-names.mdx - - page: Other - path: ./openapi-pages/extensions/others.mdx - slug: others - - section: Workflow & Automation + - page: Property names + path: ./openapi-pages/extensions/property-names.mdx + - page: Schema names + path: ./openapi-pages/extensions/schema-names.mdx + - page: Server names + path: ./openapi-pages/extensions/server-names.mdx + - section: Workflow & automation skip-slug: true contents: - - page: Overlay Customizations + - page: Overlay customizations path: ./openapi-pages/overrides.mdx - - page: Sync your OpenAPI Specification + - page: Sync your OpenAPI specification path: ./openapi-pages/automation.mdx - - section: Integrate your Server Framework + - section: Integrate your server framework slug: frameworks contents: - page: FastAPI @@ -68,34 +87,49 @@ navigation: - section: Channels slug: channels contents: - - page: Publish/Subscribe Operations + - page: Publish/subscribe operations path: ./asyncapi-pages/channels/pubsub.mdx slug: pubsub - - page: Message Formats + - page: Message formats path: ./asyncapi-pages/channels/messages.mdx slug: messages - - page: Message Bindings + - page: Message bindings path: ./asyncapi-pages/channels/bindings.mdx slug: bindings - section: Extensions slug: extensions contents: + - page: Overview + path: ./asyncapi-pages/extensions/overview.md - page: Audiences path: ./asyncapi-pages/extensions/audiences.mdx - - page: SDK Method Names + - page: Availability + path: ./asyncapi-pages/extensions/availability.mdx + - page: Error handling + path: ./asyncapi-pages/extensions/error-handling.mdx + - page: Request + response examples + path: ./asyncapi-pages/extensions/examples.mdx + - page: Ignoring operations, channels, or schemas + path: ./asyncapi-pages/extensions/ignore.mdx + - page: SDK method names path: ./asyncapi-pages/extensions/method-names.mdx slug: method-names - - page: Parameter Names + - page: Pagination + path: ./asyncapi-pages/extensions/pagination.mdx + - page: Parameter names path: ./asyncapi-pages/extensions/parameter-names.mdx - - page: Other - path: ./asyncapi-pages/extensions/others.mdx - slug: others - - section: Workflow & Automation + - page: Retry behavior + path: ./asyncapi-pages/extensions/retry.mdx + - page: Server names + path: ./asyncapi-pages/extensions/server-name.mdx + - page: Streaming operations + path: ./asyncapi-pages/extensions/streaming.mdx + - section: Workflow & automation skip-slug: true contents: - - page: Overlay Customizations + - page: Overlay customizations path: ./asyncapi-pages/overrides.mdx - - page: Sync your AsyncAPI Specification + - page: Sync your AsyncAPI specification path: ./asyncapi-pages/automation.mdx - section: OpenRPC collapsed: true @@ -110,34 +144,55 @@ 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 path: ./openrpc-pages/methods/notifications.mdx slug: notifications - - page: Batch Requests + - page: Batch requests path: ./openrpc-pages/methods/batch.mdx slug: batch - section: Extensions slug: extensions contents: + - page: Overview + path: ./openrpc-pages/extensions/overview.md - page: Audiences path: ./openrpc-pages/extensions/audiences.mdx - - page: SDK Method Names + - page: Availability + path: ./openrpc-pages/extensions/availability.mdx + - page: Base path + path: ./openrpc-pages/extensions/base-path.mdx + - page: Error handling + path: ./openrpc-pages/extensions/error-handling.mdx + - page: Request + response examples + path: ./openrpc-pages/extensions/examples.mdx + - page: Ignoring methods or schemas + path: ./openrpc-pages/extensions/ignore.mdx + - page: SDK method names path: ./openrpc-pages/extensions/method-names.mdx slug: method-names - - page: Parameter Names + - page: Pagination + path: ./openrpc-pages/extensions/pagination.mdx + - page: Parameter names path: ./openrpc-pages/extensions/parameter-names.mdx - - page: Other - path: ./openrpc-pages/extensions/others.mdx - slug: others - - section: Workflow & Automation + - page: Retry behavior + path: ./openrpc-pages/extensions/retry.mdx + - page: SDK group names + path: ./openrpc-pages/extensions/sdk-group-name.mdx + - page: Server names + path: ./openrpc-pages/extensions/server-name.mdx + - page: Streaming operations + path: ./openrpc-pages/extensions/streaming.mdx + - page: Timeout settings + path: ./openrpc-pages/extensions/timeout.mdx + - section: Workflow & automation skip-slug: true contents: - - page: Overlay Customizations + - page: Overlay customizations path: ./openrpc-pages/overrides.mdx - - page: Sync your OpenRPC Specification + - page: Sync your OpenRPC specification path: ./openrpc-pages/automation.mdx - section: gRPC collapsed: true @@ -152,34 +207,59 @@ navigation: - section: Services slug: services contents: - - page: gRPC Services + - page: gRPC services path: ./grpc-pages/services/grpc-services.mdx slug: grpc-services - page: Streaming path: ./grpc-pages/services/streaming.mdx slug: streaming - - page: Error Handling + - page: Error handling path: ./grpc-pages/services/errors.mdx slug: errors - section: Extensions slug: extensions contents: + - page: Overview + path: ./grpc-pages/extensions/overview.md - page: Audiences path: ./grpc-pages/extensions/audiences.mdx - - page: SDK Method Names + - page: Availability + path: ./grpc-pages/extensions/availability.mdx + - page: Base path + path: ./grpc-pages/extensions/base-path.mdx + - page: Error handling + path: ./grpc-pages/extensions/error-handling.mdx + - page: Request + response examples + path: ./grpc-pages/extensions/examples.mdx + - page: Ignoring services, methods, or messages + path: ./grpc-pages/extensions/ignore.mdx + - page: SDK method names path: ./grpc-pages/extensions/method-names.mdx slug: method-names - - page: Parameter Names + - page: Pagination + path: ./grpc-pages/extensions/pagination.mdx + - page: Parameter names path: ./grpc-pages/extensions/parameter-names.mdx - - page: Other - path: ./grpc-pages/extensions/others.mdx - slug: others - - section: Workflow & Automation + - page: Retry behavior + path: ./grpc-pages/extensions/retry.mdx + - page: SDK group names + path: ./grpc-pages/extensions/sdk-group-name.mdx + - page: Server names + path: ./grpc-pages/extensions/server-name.mdx + - page: Streaming operations + path: ./grpc-pages/extensions/streaming.mdx + - page: Timeout settings + path: ./grpc-pages/extensions/timeout.mdx + - page: Union naming + path: ./grpc-pages/extensions/union-naming.mdx + - page: Validation + path: ./grpc-pages/extensions/validation.mdx + - section: Workflow & automation skip-slug: true contents: - - page: Overlay Customizations + - page: Overlay customizations path: ./grpc-pages/overrides.mdx - - page: Sync your gRPC Specification + - page: Sync your gRPC specification path: ./grpc-pages/automation.mdx - section: Fern Definition collapsed: true @@ -195,16 +275,16 @@ navigation: contents: - page: Overview path: ./ferndef-pages/endpoints.mdx - - page: HTTP JSON Endpoints + - page: HTTP JSON endpoints path: ./ferndef-pages/endpoints/rest.mdx slug: http - - page: Multipart Form Uploads + - page: Multipart form uploads path: ./ferndef-pages/endpoints/multipart.mdx slug: multipart - 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 @@ -225,14 +305,14 @@ 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 path: ./ferndef-pages/api-yml/overview.mdx - page: Environments path: ./ferndef-pages/api-yml/environments.mdx - - page: Global Headers + - page: Global headers path: ./ferndef-pages/api-yml/global-configuration.mdx - page: Errors path: ./ferndef-pages/api-yml/errors.mdx @@ -241,7 +321,7 @@ navigation: contents: - page: Packages path: ./ferndef-pages/packages.mdx - - page: Depending on Other APIs + - page: Depending on other APIs path: ./ferndef-pages/depending-on-other-apis.mdx - page: Export to OpenAPI slug: export-openapi diff --git a/fern/products/api-def/asyncapi-pages/extensions/availability.mdx b/fern/products/api-def/asyncapi-pages/extensions/availability.mdx new file mode 100644 index 000000000..9faa01208 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/availability.mdx @@ -0,0 +1,17 @@ +--- +title: Availability +description: Mark features as available in specific SDK versions using `x-fern-availability` extension +--- + +Mark features as available in specific SDK versions: + +```yaml title="asyncapi.yml" {6-8} +operations: + newFeature: + action: send + channel: + $ref: '#/channels/new~1feature' + x-fern-availability: + status: beta + message: "This feature is in beta and may change" +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/error-handling.mdx b/fern/products/api-def/asyncapi-pages/extensions/error-handling.mdx new file mode 100644 index 000000000..5350edc02 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/error-handling.mdx @@ -0,0 +1,24 @@ +--- +title: Error handling +description: Configure error handling for operations using `x-fern-error-handling` extension +--- + +Configure error handling for operations: + +```yaml title="asyncapi.yml" {6-16} +operations: + sendMessage: + action: send + channel: + $ref: '#/channels/messages' + x-fern-error-handling: + error_schema: + $ref: '#/components/schemas/MessageError' + error_status_codes: + - 400 + - 429 + - 500 + retry_on_errors: + - 429 + - 500 +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/examples.mdx b/fern/products/api-def/asyncapi-pages/extensions/examples.mdx new file mode 100644 index 000000000..0affa6767 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/examples.mdx @@ -0,0 +1,30 @@ +--- +title: Request + response examples +description: Provide additional examples for better SDK documentation using `x-fern-examples` extension +--- + +Provide additional examples for better SDK documentation: + +```yaml title="asyncapi.yml" {8-20} +components: + messages: + UserEvent: + contentType: application/json + payload: + $ref: '#/components/schemas/User' + x-fern-examples: + - name: NewUserSignup + summary: Example of a new user signup event + payload: + id: "user_123" + email: "john@example.com" + name: "John Doe" + status: "active" + - name: UserDeactivation + summary: Example of user deactivation event + payload: + id: "user_456" + email: "jane@example.com" + name: "Jane Smith" + status: "inactive" +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/ignore.mdx b/fern/products/api-def/asyncapi-pages/extensions/ignore.mdx new file mode 100644 index 000000000..5a2a76278 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/ignore.mdx @@ -0,0 +1,24 @@ +--- +title: Ignoring operations, channels, or schemas +description: Skip reading specific AsyncAPI elements using `x-fern-ignore` extension +--- + +Use `x-fern-ignore` to exclude specific operations, channels, or schemas from SDK generation: + +```yaml title="asyncapi.yml" {6-7, 13-14} +operations: + debugOperation: + action: send + channel: + $ref: '#/channels/debug' + x-fern-ignore: true + summary: Debug operation (internal only) + +channels: + internal/debug: + address: internal/debug + x-fern-ignore: true + messages: + DebugMessage: + $ref: '#/components/messages/DebugMessage' +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/others.mdx b/fern/products/api-def/asyncapi-pages/extensions/others.mdx deleted file mode 100644 index cbc7d15af..000000000 --- a/fern/products/api-def/asyncapi-pages/extensions/others.mdx +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Other Extensions -subtitle: Additional Fern extensions for AsyncAPI specifications ---- - -Fern supports various extensions to enhance your AsyncAPI specifications and improve the generated SDKs and documentation. - -## `x-fern-ignore` - -Use `x-fern-ignore` to exclude specific operations, channels, or schemas from SDK generation: - -```yaml title="asyncapi.yml" {6-7, 13-14} -operations: - debugOperation: - action: send - channel: - $ref: '#/channels/debug' - x-fern-ignore: true - summary: Debug operation (internal only) - -channels: - internal/debug: - address: internal/debug - x-fern-ignore: true - messages: - DebugMessage: - $ref: '#/components/messages/DebugMessage' -``` - -## `x-fern-examples` - -Provide additional examples for better SDK documentation: - -```yaml title="asyncapi.yml" {8-20} -components: - messages: - UserEvent: - contentType: application/json - payload: - $ref: '#/components/schemas/User' - x-fern-examples: - - name: NewUserSignup - summary: Example of a new user signup event - payload: - id: "user_123" - email: "john@example.com" - name: "John Doe" - status: "active" - - name: UserDeactivation - summary: Example of user deactivation event - payload: - id: "user_456" - email: "jane@example.com" - name: "Jane Smith" - status: "inactive" -``` - -## `x-fern-pagination` - -Configure pagination for operations that return multiple results: - -```yaml title="asyncapi.yml" {6-11} -operations: - listUserEvents: - action: receive - channel: - $ref: '#/channels/user~1events' - x-fern-pagination: - cursor: next_cursor - results: events - next_cursor: pagination.next_cursor - has_next_page: pagination.has_next_page -``` - -## `x-fern-retry` - -Configure retry behavior for operations: - -```yaml title="asyncapi.yml" {6-10} -operations: - sendCriticalAlert: - action: send - channel: - $ref: '#/channels/alerts' - x-fern-retry: - max_attempts: 3 - exponential_backoff: true - initial_delay: 1000 - max_delay: 30000 -``` - -## `x-fern-streaming` - -Mark operations as streaming for appropriate SDK generation: - -```yaml title="asyncapi.yml" {6-9} -operations: - streamEvents: - action: receive - channel: - $ref: '#/channels/event~1stream' - x-fern-streaming: - type: server_sent_events - termination: client_closes -``` - -## `x-fern-error-handling` - -Configure error handling for operations: - -```yaml title="asyncapi.yml" {6-16} -operations: - sendMessage: - action: send - channel: - $ref: '#/channels/messages' - x-fern-error-handling: - error_schema: - $ref: '#/components/schemas/MessageError' - error_status_codes: - - 400 - - 429 - - 500 - retry_on_errors: - - 429 - - 500 -``` - -## `x-fern-server-name` - -Specify custom names for servers: - -```yaml title="asyncapi.yml" {4-5} -servers: - production: - host: api.yourcompany.com - x-fern-server-name: Production - protocol: wss - staging: - host: staging.api.yourcompany.com - x-fern-server-name: Staging - protocol: wss -``` - -## `x-fern-availability` - -Mark features as available in specific SDK versions: - -```yaml title="asyncapi.yml" {6-8} -operations: - newFeature: - action: send - channel: - $ref: '#/channels/new~1feature' - x-fern-availability: - status: beta - message: "This feature is in beta and may change" -``` - -These extensions help you create more robust and user-friendly SDKs while maintaining full control over the generated code structure and behavior. \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/overview.md b/fern/products/api-def/asyncapi-pages/extensions/overview.md new file mode 100644 index 000000000..71d836ff7 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/overview.md @@ -0,0 +1,25 @@ +--- +title: Overview of AsyncAPI extensions +description: Learn about Fern's AsyncAPI extensions for generating higher-quality SDKs +--- + +Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. + +## Available extensions + +The table below shows all available extensions and links to detailed documentation for each one. + +| Extension | Description | +| --- | --- | +| [`x-fern-ignore`](./ignore) | Skip reading specific operations, channels, or schemas | +| [`x-fern-examples`](./examples) | Provide additional examples for better SDK documentation | +| [`x-fern-pagination`](./pagination) | Configure pagination for operations that return multiple results | +| [`x-fern-retry`](./retry) | Configure retry behavior for operations | +| [`x-fern-streaming`](./streaming) | Mark operations as streaming for appropriate SDK generation | +| [`x-fern-error-handling`](./error-handling) | Configure error handling for operations | +| [`x-fern-server-name`](./server-name) | Specify custom names for servers | +| [`x-fern-availability`](./availability) | Mark features as available in specific SDK versions | + + + If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. + \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/pagination.mdx b/fern/products/api-def/asyncapi-pages/extensions/pagination.mdx new file mode 100644 index 000000000..7e40ba9ca --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/pagination.mdx @@ -0,0 +1,19 @@ +--- +title: Pagination +description: Configure pagination for operations that return multiple results using `x-fern-pagination` extension +--- + +Configure pagination for operations that return multiple results: + +```yaml title="asyncapi.yml" {6-11} +operations: + listUserEvents: + action: receive + channel: + $ref: '#/channels/user~1events' + x-fern-pagination: + cursor: next_cursor + results: events + next_cursor: pagination.next_cursor + has_next_page: pagination.has_next_page +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/retry.mdx b/fern/products/api-def/asyncapi-pages/extensions/retry.mdx new file mode 100644 index 000000000..58cd3d997 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/retry.mdx @@ -0,0 +1,19 @@ +--- +title: Retry behavior +description: Configure retry behavior for operations using `x-fern-retry` extension +--- + +Configure retry behavior for operations: + +```yaml title="asyncapi.yml" {6-10} +operations: + sendCriticalAlert: + action: send + channel: + $ref: '#/channels/alerts' + x-fern-retry: + max_attempts: 3 + exponential_backoff: true + initial_delay: 1000 + max_delay: 30000 +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/server-name.mdx b/fern/products/api-def/asyncapi-pages/extensions/server-name.mdx new file mode 100644 index 000000000..085298ca1 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/server-name.mdx @@ -0,0 +1,18 @@ +--- +title: Server names +description: Specify custom names for servers using `x-fern-server-name` extension +--- + +Specify custom names for servers: + +```yaml title="asyncapi.yml" {4-5} +servers: + production: + host: api.yourcompany.com + x-fern-server-name: Production + protocol: wss + staging: + host: staging.api.yourcompany.com + x-fern-server-name: Staging + protocol: wss +``` \ No newline at end of file diff --git a/fern/products/api-def/asyncapi-pages/extensions/streaming.mdx b/fern/products/api-def/asyncapi-pages/extensions/streaming.mdx new file mode 100644 index 000000000..fd66cd5f5 --- /dev/null +++ b/fern/products/api-def/asyncapi-pages/extensions/streaming.mdx @@ -0,0 +1,17 @@ +--- +title: Streaming operations +description: Mark operations as streaming for appropriate SDK generation using `x-fern-streaming` extension +--- + +Mark operations as streaming for appropriate SDK generation: + +```yaml title="asyncapi.yml" {6-9} +operations: + streamEvents: + action: receive + channel: + $ref: '#/channels/event~1stream' + x-fern-streaming: + type: server_sent_events + termination: client_closes +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/availability.mdx b/fern/products/api-def/grpc-pages/extensions/availability.mdx new file mode 100644 index 000000000..29bdae6db --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/availability.mdx @@ -0,0 +1,30 @@ +--- +title: Availability +description: Mark features as available in specific SDK versions using `x-fern-availability` extension +--- + +Mark features as available in specific SDK versions: + +```protobuf title="availability_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc GetUser(GetUserRequest) returns (User); + + rpc GetUserAnalytics(GetUserAnalyticsRequest) returns (UserAnalytics) { + option (x_fern_availability) = '{ + "status": "beta", + "message": "This feature is in beta and may change" + }'; + } + + rpc ExperimentalSearch(ExperimentalSearchRequest) returns (SearchResults) { + option (x_fern_availability) = '{ + "status": "experimental", + "message": "This is an experimental feature and may be removed" + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/base-path.mdx b/fern/products/api-def/grpc-pages/extensions/base-path.mdx new file mode 100644 index 000000000..7d9949e21 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/base-path.mdx @@ -0,0 +1,18 @@ +--- +title: Base path +description: Configure base paths for generated SDK clients using `x-fern-base-path` extension +--- + +Configure base paths for generated SDK clients: + +```protobuf title="base_path_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + option (x_fern_base_path) = "/api/v1"; + + rpc GetUser(GetUserRequest) returns (User); +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/error-handling.mdx b/fern/products/api-def/grpc-pages/extensions/error-handling.mdx new file mode 100644 index 000000000..aaef8b687 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/error-handling.mdx @@ -0,0 +1,31 @@ +--- +title: Error handling +description: Configure error handling for methods using `x-fern-error-handling` extension +--- + +Configure error handling for methods: + +```protobuf title="error_handling_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc CreateUser(CreateUserRequest) returns (User) { + option (x_fern_error_handling) = '{ + "ALREADY_EXISTS": { + "error_name": "UserAlreadyExistsError", + "user_friendly_message": "A user with this email already exists" + }, + "INVALID_ARGUMENT": { + "error_name": "ValidationError", + "user_friendly_message": "Please check your input and try again" + }, + "RESOURCE_EXHAUSTED": { + "error_name": "RateLimitError", + "retry_after_seconds": 60 + } + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/examples.mdx b/fern/products/api-def/grpc-pages/extensions/examples.mdx new file mode 100644 index 000000000..40e83e05e --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/examples.mdx @@ -0,0 +1,53 @@ +--- +title: Request + response examples +description: Provide additional examples for better SDK documentation using `x-fern-examples` extension +--- + +Provide additional examples for better SDK documentation: + +```protobuf title="user_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc CreateUser(CreateUserRequest) returns (User) { + option (x_fern_examples) = '{ + "StandardUser": { + "description": "Create a regular user account", + "request": { + "email": "john@example.com", + "name": "John Doe", + "age": 30, + "preferences": { + "theme": "dark", + "notifications": true + } + }, + "response": { + "id": "user_123", + "email": "john@example.com", + "name": "John Doe", + "created_at": "2024-01-15T10:30:00Z" + } + }, + "AdminUser": { + "description": "Create an admin user with special permissions", + "request": { + "email": "admin@example.com", + "name": "Admin User", + "role": "admin", + "permissions": ["read", "write", "delete"] + }, + "response": { + "id": "user_456", + "email": "admin@example.com", + "name": "Admin User", + "role": "admin", + "created_at": "2024-01-15T10:30:00Z" + } + } + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/ignore.mdx b/fern/products/api-def/grpc-pages/extensions/ignore.mdx new file mode 100644 index 000000000..41462a836 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/ignore.mdx @@ -0,0 +1,35 @@ +--- +title: Ignoring services, methods, or messages +description: Skip reading specific gRPC elements using `x-fern-ignore` extension +--- + +Use `x-fern-ignore` to exclude specific services, methods or messages from SDK generation: + +```protobuf title="user_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc GetUser(GetUserRequest) returns (User); + + // Exclude internal debugging method + rpc DebugUserData(DebugUserRequest) returns (DebugUserResponse) { + option (x_fern_ignore) = true; + } + + // Exclude experimental method + rpc ExperimentalFeature(ExperimentalRequest) returns (ExperimentalResponse) { + option (x_fern_ignore) = true; + } +} + +// Exclude internal message from SDK +message InternalUserData { + option (x_fern_ignore) = true; + + string internal_id = 1; + repeated string debug_flags = 2; + map system_metadata = 3; +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/others.mdx b/fern/products/api-def/grpc-pages/extensions/others.mdx deleted file mode 100644 index 56d7dbf7c..000000000 --- a/fern/products/api-def/grpc-pages/extensions/others.mdx +++ /dev/null @@ -1,403 +0,0 @@ ---- -title: Other Extensions -subtitle: Additional Fern extensions for gRPC specifications ---- - -Fern supports various extensions to enhance your gRPC specifications and improve the generated SDKs and documentation. - -## `x-fern-ignore` - -Use `x-fern-ignore` to exclude specific services, methods or messages from SDK generation: - -```protobuf title="user_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc GetUser(GetUserRequest) returns (User); - - // Exclude internal debugging method - rpc DebugUserData(DebugUserRequest) returns (DebugUserResponse) { - option (x_fern_ignore) = true; - } - - // Exclude experimental method - rpc ExperimentalFeature(ExperimentalRequest) returns (ExperimentalResponse) { - option (x_fern_ignore) = true; - } -} - -// Exclude internal message from SDK -message InternalUserData { - option (x_fern_ignore) = true; - - string internal_id = 1; - repeated string debug_flags = 2; - map system_metadata = 3; -} -``` - -## `x-fern-examples` - -Provide additional examples for better SDK documentation: - -```protobuf title="user_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc CreateUser(CreateUserRequest) returns (User) { - option (x_fern_examples) = '{ - "StandardUser": { - "description": "Create a regular user account", - "request": { - "email": "john@example.com", - "name": "John Doe", - "age": 30, - "preferences": { - "theme": "dark", - "notifications": true - } - }, - "response": { - "id": "user_123", - "email": "john@example.com", - "name": "John Doe", - "created_at": "2024-01-15T10:30:00Z" - } - }, - "AdminUser": { - "description": "Create an admin user with special permissions", - "request": { - "email": "admin@example.com", - "name": "Admin User", - "role": "admin", - "permissions": ["read", "write", "delete"] - }, - "response": { - "id": "user_456", - "email": "admin@example.com", - "name": "Admin User", - "role": "admin", - "created_at": "2024-01-15T10:30:00Z" - } - } - }'; - } -} -``` - -## `x-fern-pagination` - -Configure pagination for methods that return lists: - -```protobuf title="pagination_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) { - option (x_fern_pagination) = '{ - "cursor": "page_token", - "results": "users", - "next_cursor": "next_page_token", - "has_next_page": "has_more" - }'; - } -} - -message ListUsersRequest { - int32 page_size = 1; - string page_token = 2; - string filter = 3; -} - -message ListUsersResponse { - repeated User users = 1; - string next_page_token = 2; - bool has_more = 3; - int32 total_count = 4; -} -``` - -## `x-fern-retry` - -Configure retry behavior for methods: - -```protobuf title="retry_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc ProcessPayment(ProcessPaymentRequest) returns (PaymentResult) { - option (x_fern_retry) = '{ - "max_attempts": 3, - "exponential_backoff": true, - "initial_delay_ms": 1000, - "max_delay_ms": 30000, - "retry_on_status": ["UNAVAILABLE", "DEADLINE_EXCEEDED", "INTERNAL"] - }'; - } - - rpc UploadFile(UploadFileRequest) returns (UploadFileResponse) { - option (x_fern_retry) = '{ - "max_attempts": 5, - "exponential_backoff": true, - "initial_delay_ms": 2000, - "max_delay_ms": 60000 - }'; - } -} -``` - -## `x-fern-timeout` - -Configure timeout settings for methods: - -```protobuf title="timeout_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc GenerateReport(GenerateReportRequest) returns (ReportResult) { - option (x_fern_timeout) = '{ - "seconds": 300, - "description": "Report generation can take up to 5 minutes" - }'; - } - - rpc QuickUserLookup(UserLookupRequest) returns (User) { - option (x_fern_timeout) = '{ - "seconds": 5, - "description": "Quick lookup should complete within 5 seconds" - }'; - } -} -``` - -## `x-fern-error-handling` - -Configure error handling for methods: - -```protobuf title="error_handling_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc CreateUser(CreateUserRequest) returns (User) { - option (x_fern_error_handling) = '{ - "ALREADY_EXISTS": { - "error_name": "UserAlreadyExistsError", - "user_friendly_message": "A user with this email already exists" - }, - "INVALID_ARGUMENT": { - "error_name": "ValidationError", - "user_friendly_message": "Please check your input and try again" - }, - "RESOURCE_EXHAUSTED": { - "error_name": "RateLimitError", - "retry_after_seconds": 60 - } - }'; - } -} -``` - -## `x-fern-availability` - -Mark features as available in specific SDK versions: - -```protobuf title="availability_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc GetUser(GetUserRequest) returns (User); - - rpc GetUserAnalytics(GetUserAnalyticsRequest) returns (UserAnalytics) { - option (x_fern_availability) = '{ - "status": "beta", - "message": "This feature is in beta and may change" - }'; - } - - rpc ExperimentalSearch(ExperimentalSearchRequest) returns (SearchResults) { - option (x_fern_availability) = '{ - "status": "experimental", - "message": "This is an experimental feature and may be removed" - }'; - } -} -``` - -## `x-fern-streaming` - -Mark methods as streaming for appropriate SDK generation: - -```protobuf title="streaming_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - rpc StreamEvents(StreamEventsRequest) returns (stream Event) { - option (x_fern_streaming) = '{ - "type": "server_streaming", - "termination": "client_closes" - }'; - } - - rpc UploadData(stream UploadDataRequest) returns (UploadResult) { - option (x_fern_streaming) = '{ - "type": "client_streaming", - "termination": "client_closes" - }'; - } - - rpc Chat(stream ChatMessage) returns (stream ChatMessage) { - option (x_fern_streaming) = '{ - "type": "bidirectional_streaming", - "termination": "either_closes" - }'; - } -} -``` - -## `x-fern-server-name` - -Specify custom names for different server environments: - -```protobuf title="server_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - option (x_fern_server_name_production) = "Production"; - option (x_fern_server_name_staging) = "Staging"; - option (x_fern_server_name_development) = "Development"; - - rpc GetUser(GetUserRequest) returns (User); -} -``` - -## `x-fern-base-path` - -Configure base paths for generated SDK clients: - -```protobuf title="base_path_service.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - option (x_fern_base_path) = "/api/v1"; - - rpc GetUser(GetUserRequest) returns (User); -} -``` - -## `x-fern-sdk-group-name` - -Group related services in the SDK: - -```protobuf title="grouped_services.proto" -syntax = "proto3"; - -package userservice.v1; - -service UserService { - option (x_fern_sdk_group_name) = "users"; - - rpc CreateUser(CreateUserRequest) returns (User); - rpc GetUser(GetUserRequest) returns (User); -} - -service UserProfileService { - option (x_fern_sdk_group_name) = "users"; - - rpc GetProfile(GetProfileRequest) returns (UserProfile); - rpc UpdateProfile(UpdateProfileRequest) returns (UserProfile); -} - -service AuthService { - option (x_fern_sdk_group_name) = "auth"; - - rpc Login(LoginRequest) returns (LoginResponse); - rpc Logout(LogoutRequest) returns (google.protobuf.Empty); -} -``` - -This generates SDKs with grouped services: - -```typescript -client.users.createUser(...) -client.users.getUser(...) -client.users.getProfile(...) -client.users.updateProfile(...) -client.auth.login(...) -client.auth.logout(...) -``` - -## `x-fern-union-naming` - -Configure naming for oneof fields in SDKs: - -```protobuf title="union_naming.proto" -syntax = "proto3"; - -package userservice.v1; - -message NotificationTarget { - oneof target { - option (x_fern_union_naming) = "discriminated"; - - string user_id = 1 [(x_fern_parameter_name) = "userId"]; - string group_id = 2 [(x_fern_parameter_name) = "groupId"]; - BroadcastTarget broadcast = 3; - } -} -``` - -## `x-fern-validation` - -Add validation rules for message fields: - -```protobuf title="validation_service.proto" -syntax = "proto3"; - -package userservice.v1; - -message CreateUserRequest { - string email = 1 [ - (x_fern_validation) = '{ - "format": "email", - "required": true - }' - ]; - - string name = 2 [ - (x_fern_validation) = '{ - "min_length": 1, - "max_length": 100, - "required": true - }' - ]; - - int32 age = 3 [ - (x_fern_validation) = '{ - "minimum": 0, - "maximum": 120 - }' - ]; -} -``` - -These extensions help you create more robust and user-friendly SDKs while maintaining full control over the generated code structure and behavior. \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/overview.md b/fern/products/api-def/grpc-pages/extensions/overview.md new file mode 100644 index 000000000..3e2f8cf0a --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/overview.md @@ -0,0 +1,30 @@ +--- +title: Overview of gRPC extensions +description: Learn about Fern's gRPC extensions for generating higher-quality SDKs +--- + +Fern supports a variety of gRPC extensions that enhance your API specification and generate higher-quality SDKs. + +## Available extensions + +The table below shows all available extensions and links to detailed documentation for each one. + +| Extension | Description | +| --- | --- | +| [`x-fern-ignore`](./ignore) | Skip reading specific services, methods, or messages | +| [`x-fern-examples`](./examples) | Provide additional examples for better SDK documentation | +| [`x-fern-pagination`](./pagination) | Configure pagination for methods that return lists | +| [`x-fern-retry`](./retry) | Configure retry behavior for methods | +| [`x-fern-timeout`](./timeout) | Configure timeout settings for methods | +| [`x-fern-error-handling`](./error-handling) | Configure error handling for methods | +| [`x-fern-availability`](./availability) | Mark features as available in specific SDK versions | +| [`x-fern-streaming`](./streaming) | Mark methods as streaming for appropriate SDK generation | +| [`x-fern-server-name`](./server-name) | Specify custom names for different server environments | +| [`x-fern-base-path`](./base-path) | Configure base paths for generated SDK clients | +| [`x-fern-sdk-group-name`](./sdk-group-name) | Group related services in the SDK | +| [`x-fern-union-naming`](./union-naming) | Configure naming for oneof fields in SDKs | +| [`x-fern-validation`](./validation) | Add validation rules for message fields | + + + If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. + \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/pagination.mdx b/fern/products/api-def/grpc-pages/extensions/pagination.mdx new file mode 100644 index 000000000..a8a9fea20 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/pagination.mdx @@ -0,0 +1,36 @@ +--- +title: Pagination +description: Configure pagination for methods that return lists using `x-fern-pagination` extension +--- + +Configure pagination for methods that return lists: + +```protobuf title="pagination_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) { + option (x_fern_pagination) = '{ + "cursor": "page_token", + "results": "users", + "next_cursor": "next_page_token", + "has_next_page": "has_more" + }'; + } +} + +message ListUsersRequest { + int32 page_size = 1; + string page_token = 2; + string filter = 3; +} + +message ListUsersResponse { + repeated User users = 1; + string next_page_token = 2; + bool has_more = 3; + int32 total_count = 4; +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/retry.mdx b/fern/products/api-def/grpc-pages/extensions/retry.mdx new file mode 100644 index 000000000..86a54cca5 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/retry.mdx @@ -0,0 +1,33 @@ +--- +title: Retry behavior +description: Configure retry behavior for methods using `x-fern-retry` extension +--- + +Configure retry behavior for methods: + +```protobuf title="retry_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc ProcessPayment(ProcessPaymentRequest) returns (PaymentResult) { + option (x_fern_retry) = '{ + "max_attempts": 3, + "exponential_backoff": true, + "initial_delay_ms": 1000, + "max_delay_ms": 30000, + "retry_on_status": ["UNAVAILABLE", "DEADLINE_EXCEEDED", "INTERNAL"] + }'; + } + + rpc UploadFile(UploadFileRequest) returns (UploadFileResponse) { + option (x_fern_retry) = '{ + "max_attempts": 5, + "exponential_backoff": true, + "initial_delay_ms": 2000, + "max_delay_ms": 60000 + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/sdk-group-name.mdx b/fern/products/api-def/grpc-pages/extensions/sdk-group-name.mdx new file mode 100644 index 000000000..1b6a0c6b7 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/sdk-group-name.mdx @@ -0,0 +1,44 @@ +--- +title: SDK group names +description: Group related services in the SDK using `x-fern-sdk-group-name` extension +--- + +Group related services in the SDK: + +```protobuf title="grouped_services.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + option (x_fern_sdk_group_name) = "users"; + + rpc CreateUser(CreateUserRequest) returns (User); + rpc GetUser(GetUserRequest) returns (User); +} + +service UserProfileService { + option (x_fern_sdk_group_name) = "users"; + + rpc GetProfile(GetProfileRequest) returns (UserProfile); + rpc UpdateProfile(UpdateProfileRequest) returns (UserProfile); +} + +service AuthService { + option (x_fern_sdk_group_name) = "auth"; + + rpc Login(LoginRequest) returns (LoginResponse); + rpc Logout(LogoutRequest) returns (google.protobuf.Empty); +} +``` + +This generates SDKs with grouped services: + +```typescript +client.users.createUser(...) +client.users.getUser(...) +client.users.getProfile(...) +client.users.updateProfile(...) +client.auth.login(...) +client.auth.logout(...) +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/server-name.mdx b/fern/products/api-def/grpc-pages/extensions/server-name.mdx new file mode 100644 index 000000000..5adb06d9f --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/server-name.mdx @@ -0,0 +1,20 @@ +--- +title: Server names +description: Specify custom names for different server environments using `x-fern-server-name` extension +--- + +Specify custom names for different server environments: + +```protobuf title="server_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + option (x_fern_server_name_production) = "Production"; + option (x_fern_server_name_staging) = "Staging"; + option (x_fern_server_name_development) = "Development"; + + rpc GetUser(GetUserRequest) returns (User); +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/streaming.mdx b/fern/products/api-def/grpc-pages/extensions/streaming.mdx new file mode 100644 index 000000000..bad97eb51 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/streaming.mdx @@ -0,0 +1,35 @@ +--- +title: Streaming operations +description: Mark methods as streaming for appropriate SDK generation using `x-fern-streaming` extension +--- + +Mark methods as streaming for appropriate SDK generation: + +```protobuf title="streaming_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc StreamEvents(StreamEventsRequest) returns (stream Event) { + option (x_fern_streaming) = '{ + "type": "server_streaming", + "termination": "client_closes" + }'; + } + + rpc UploadData(stream UploadDataRequest) returns (UploadResult) { + option (x_fern_streaming) = '{ + "type": "client_streaming", + "termination": "client_closes" + }'; + } + + rpc Chat(stream ChatMessage) returns (stream ChatMessage) { + option (x_fern_streaming) = '{ + "type": "bidirectional_streaming", + "termination": "either_closes" + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/timeout.mdx b/fern/products/api-def/grpc-pages/extensions/timeout.mdx new file mode 100644 index 000000000..f028b9475 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/timeout.mdx @@ -0,0 +1,28 @@ +--- +title: Timeout settings +description: Configure timeout settings for methods using `x-fern-timeout` extension +--- + +Configure timeout settings for methods: + +```protobuf title="timeout_service.proto" +syntax = "proto3"; + +package userservice.v1; + +service UserService { + rpc GenerateReport(GenerateReportRequest) returns (ReportResult) { + option (x_fern_timeout) = '{ + "seconds": 300, + "description": "Report generation can take up to 5 minutes" + }'; + } + + rpc QuickUserLookup(UserLookupRequest) returns (User) { + option (x_fern_timeout) = '{ + "seconds": 5, + "description": "Quick lookup should complete within 5 seconds" + }'; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/union-naming.mdx b/fern/products/api-def/grpc-pages/extensions/union-naming.mdx new file mode 100644 index 000000000..49fe4a783 --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/union-naming.mdx @@ -0,0 +1,22 @@ +--- +title: Union naming +description: Configure naming for oneof fields in SDKs using `x-fern-union-naming` extension +--- + +Configure naming for oneof fields in SDKs: + +```protobuf title="union_naming.proto" +syntax = "proto3"; + +package userservice.v1; + +message NotificationTarget { + oneof target { + option (x_fern_union_naming) = "discriminated"; + + string user_id = 1 [(x_fern_parameter_name) = "userId"]; + string group_id = 2 [(x_fern_parameter_name) = "groupId"]; + BroadcastTarget broadcast = 3; + } +} +``` \ No newline at end of file diff --git a/fern/products/api-def/grpc-pages/extensions/validation.mdx b/fern/products/api-def/grpc-pages/extensions/validation.mdx new file mode 100644 index 000000000..2cd41b20d --- /dev/null +++ b/fern/products/api-def/grpc-pages/extensions/validation.mdx @@ -0,0 +1,36 @@ +--- +title: Validation +description: Add validation rules for message fields using `x-fern-validation` extension +--- + +Add validation rules for message fields: + +```protobuf title="validation_service.proto" +syntax = "proto3"; + +package userservice.v1; + +message CreateUserRequest { + string email = 1 [ + (x_fern_validation) = '{ + "format": "email", + "required": true + }' + ]; + + string name = 2 [ + (x_fern_validation) = '{ + "min_length": 1, + "max_length": 100, + "required": true + }' + ]; + + int32 age = 3 [ + (x_fern_validation) = '{ + "minimum": 0, + "maximum": 120 + }' + ]; +} +``` \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/extensions/api-version.mdx b/fern/products/api-def/openapi-pages/extensions/api-version.mdx new file mode 100644 index 000000000..c06e6afee --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/api-version.mdx @@ -0,0 +1,18 @@ +--- +title: API version +description: Configure API version schemes and headers using `x-fern-version` extension +--- + +You can define your API version scheme, such as a `X-API-Version` header. The supported versions and default value are specified like so: + +```yaml title="openapi.yaml" +x-fern-version: + version: + header: X-API-Version + default: "2.0.0" + values: + - "1.0.0" + - "2.0.0" + - "latest" +paths: ... +``` \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/extensions/availability.mdx b/fern/products/api-def/openapi-pages/extensions/availability.mdx new file mode 100644 index 000000000..690249740 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/availability.mdx @@ -0,0 +1,27 @@ +--- +title: Availability +description: Mark endpoint availability status using `x-fern-availability` extension +--- + +The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags. + +The options are: + +- `beta` +- `generally-available` +- `deprecated` + +The example below marks that the `POST /pet` endpoint is `deprecated`. + +```yaml title="x-fern-availability in openapi.yml" {4} +paths: + /pet: + post: + x-fern-availability: deprecated +``` + +This renders as: + + +![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) + \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/extensions/base-path.mdx b/fern/products/api-def/openapi-pages/extensions/base-path.mdx new file mode 100644 index 000000000..df950139c --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/base-path.mdx @@ -0,0 +1,18 @@ +--- +title: Base path +description: Configure base path prepended to endpoints using `x-fern-base-path` extension +--- +## Base path + +The `x-fern-base-path` extension is used to configure the base path prepended to every endpoint. + +In the example below, we have configured the `/v1` base path so the full endpoint path is +`https://api.example.com/v1/users`. + +```yaml title="Set the base path in openapi.yml" {1} +x-fern-base-path: /v1 +servers: + - url: https://api.example.com +paths: + /users: ... +``` diff --git a/fern/products/api-def/openapi-pages/extensions/enums.mdx b/fern/products/api-def/openapi-pages/extensions/enums.mdx new file mode 100644 index 000000000..05344d7a8 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/enums.mdx @@ -0,0 +1,57 @@ +--- +title: Enum descriptions and names +description: Add descriptions and custom names to enum values using `x-fern-enum` extension +--- + +OpenAPI doesn't natively support adding descriptions to enum values. To do this in Fern you can use the `x-fern-enum` +extension. + +In the example below, we've added some descriptions to enum values. These descriptions will +propagate into the generated SDK and docs website. + +```yaml title="openapi.yml" {9-13} +components: + schemas: + CardSuit: + enum: + - clubs + - diamonds + - hearts + - spades + x-fern-enum: + clubs: + description: Some docs about clubs + spades: + description: Some docs about spades +``` + +`x-fern-enum` also supports a `name` field that allows you to customize the name of the enum in code. +This is particularly useful when you have enums that rely on symbolic characters that would otherwise cause +generated code not to compile. + +For example, the following OpenAPI + +```yaml title="openapi.yml" {9,12} +components: + schemas: + Operand: + enum: + - '>' + - '<' + x-fern-enum: + '>': + name: GreaterThan + description: Checks if value is greater than + '<': + name: LessThan + description: Checks if value is less than +``` + +would generate + +```typescript title="operand.ts" +export enum Operand { + GreaterThan = ">", + LessThan = "<" +} +``` diff --git a/fern/products/api-def/openapi-pages/extensions/examples.mdx b/fern/products/api-def/openapi-pages/extensions/examples.mdx new file mode 100644 index 000000000..4cb471d59 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/examples.mdx @@ -0,0 +1,65 @@ +--- +title: Request + response examples +description: Associate request and response examples using `x-fern-examples` extension +--- + +While OpenAPI has several fields for examples, there is no easy way +to associate a request with a response. This is especially useful when +you want to show more than one example in your documentation. + +`x-fern-examples` is an array of examples. Each element of the array +can contain `path-parameters`, `query-parameters`, `request` and `response` +examples values that are all associated. + +```yaml title="openapi.yml" {5-16} +paths: + /users/{userId}: + get: + x-fern-examples: + - path-parameters: + userId: user-1234 + response: + body: + name: Foo + ssn: 1234 + - path-parameters: + userId: user-4567 + response: + body: + name: Foo + ssn: 4567 +components: + schemas: + User: + type: object + properties: + name: + type: string + ssn: + type: integer +``` + +### Code samples + +If you'd like to specify custom code samples for your example, use `code-samples`. + +```yaml title="openapi.yml" {11-16} +paths: + /users/{userId}: + get: + x-fern-examples: + - path-parameters: + userId: user-1234 + response: + body: + name: Foo + ssn: 1234 + code-samples: + - sdk: typescript + code: | + import { UserClient } from "..."; + + client.users.get("user-1234") +``` + +If you're on the Fern Basic plan or higher for SDKs you won't have to worry about manually adding code samples! Our generators do that for you. diff --git a/fern/products/api-def/openapi-pages/extensions/global-headers.mdx b/fern/products/api-def/openapi-pages/extensions/global-headers.mdx new file mode 100644 index 000000000..254c27715 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/global-headers.mdx @@ -0,0 +1,35 @@ +--- +title: Global headers +description: Configure headers used across all endpoints using `x-fern-global-headers` extension +--- + +At times, your API will leverage certain headers for every endpoint, or the majority of them, we call these "global headers". For convenience, generated Fern SDKs expose "global headers" to easily be updated on API calls. Take for example an API key, if we declare the API key as a global header, a user will be able to plug theirs in easily: + +```python +import os + +class Client: + + def __init__(self, *, apiKey: str): +``` + +To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global. +In order to label additional headers as global, or to alias the names of global headers, you can leverage the `x-fern-global-headers` extension: + +```yaml title="openapi.yml" +x-fern-global-headers: + - header: custom_api_key + name: api_key + - header: userpool_id + optional: true +``` + +yields the following client: + +```python +import os + +class Client: + + def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str]) +``` diff --git a/fern/products/api-def/openapi-pages/extensions/ignore.mdx b/fern/products/api-def/openapi-pages/extensions/ignore.mdx new file mode 100644 index 000000000..a244e79d8 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/ignore.mdx @@ -0,0 +1,26 @@ +--- +title: Ignoring schemas or endpoints +description: Skip reading endpoints or schemas using the `x-fern-ignore` extension +--- + +If you want Fern to skip reading any endpoints or schemas, use the `x-fern-ignore` extension. + +To skip an endpoint, add `x-fern-ignore: true` at the operation level. + +```yaml title="x-fern-ignore at operation level in openapi.yml" {4} +paths: + /users: + get: + x-fern-ignore: true + ... +``` + +To skip a schema, add `x-fern-ignore: true` at the schema level. + +```yaml title="x-fern-ignore at schema level in openapi.yml" {4} +components: + schemas: + SchemaToSkip: + x-fern-ignore: true + ... +``` diff --git a/fern/products/api-def/openapi-pages/extensions/others.mdx b/fern/products/api-def/openapi-pages/extensions/others.mdx deleted file mode 100644 index b3aa4b3e3..000000000 --- a/fern/products/api-def/openapi-pages/extensions/others.mdx +++ /dev/null @@ -1,416 +0,0 @@ ---- -title: Other extensions -description: Learn about Fern's OpenAPI extensions for authentication overrides, global headers, enum descriptions and names, audiences, and more. ---- - -Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs. - -## API version - -You can define your API version scheme, such as a `X-API-Version` header. The supported versions and default value are specified like so: - -```yaml title="openapi.yaml" -x-fern-version: - version: - header: X-API-Version - default: "2.0.0" - values: - - "1.0.0" - - "2.0.0" - - "latest" -paths: ... -``` - -## Global headers - -At times, your API will leverage certain headers for every endpoint, or the majority of them, we call these "global headers". For convenience, generated Fern SDKs expose "global headers" to easily be updated on API calls. Take for example an API key, if we declare the API key as a global header, a user will be able to plug theirs in easily: - -```python -import os - -class Client: - - def __init__(self, *, apiKey: str): -``` - -To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global. -In order to label additional headers as global, or to alias the names of global headers, you can leverage the `x-fern-global-headers` extension: - -```yaml title="openapi.yml" -x-fern-global-headers: - - header: custom_api_key - name: api_key - - header: userpool_id - optional: true -``` - -yields the following client: - -```python -import os - -class Client: - - def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str]) -``` - -## Enum descriptions and names - -OpenAPI doesn't natively support adding descriptions to enum values. To do this in Fern you can use the `x-fern-enum` -extension. - -In the example below, we've added some descriptions to enum values. These descriptions will -propagate into the generated SDK and docs website. - -```yaml title="openapi.yml" {9-13} -components: - schemas: - CardSuit: - enum: - - clubs - - diamonds - - hearts - - spades - x-fern-enum: - clubs: - description: Some docs about clubs - spades: - description: Some docs about spades -``` - -`x-fern-enum` also supports a `name` field that allows you to customize the name of the enum in code. -This is particularly useful when you have enums that rely on symbolic characters that would otherwise cause -generated code not to compile. - -For example, the following OpenAPI - -```yaml title="openapi.yml" {9,12} -components: - schemas: - Operand: - enum: - - '>' - - '<' - x-fern-enum: - '>': - name: GreaterThan - description: Checks if value is greater than - '<': - name: LessThan - description: Checks if value is less than -``` - -would generate - -```typescript title="operand.ts" -export enum Operand { - GreaterThan = ">", - LessThan = "<" -} -``` - -## Schema names - -OpenAPI allows you to define inlined schemas that do not have names. - -```yaml title="Inline type in openapi.yml" {11} -components: - schemas: - Movie: - type: object - properties: - name: - type: string - cast: - type: array - items: - type: object - properties: - firstName: - type: string - lastName: - type: string - age: - type: integer -``` - -Fern automatically generates names for all the inlined schemas. For example, in this example, -Fern would generate the name `CastItem` for the inlined array item schema. - -```typescript title="Auto-generated name" {6} -export interface Movie { - name?: string; - cast?: CastItem[]; -} - -export interface CastItem { - firstName?: string; - lastName?: string; - age?: integer; -} -``` - -If you want to override the generated name, you can use the extension `x-fern-type-name`. - -```yaml title="openapi.yml" {12} -components: - schemas: - Movie: - type: object - properties: - name: - type: string - cast: - type: array - items: - type: object - x-fern-type-name: Person - properties: - firstName: - type: string - lastName: - type: string - age: - type: integer -``` - -This would replace `CastItem` with `Person` and the generated code would read more idiomatically: - -```typescript title="Overridden name" {6} -export interface Movie { - name?: string; - cast?: Person[]; -} - -export interface Person { - firstName?: string; - lastName?: string; - age?: integer; -} -``` - -## Property names - -The `x-fern-property-name` extension allows you to customize the variable name for object -properties. - -For example, if you had a property called `_metadata` in your schema but you wanted the -variable to be called `data` in your SDK you would do the following: - -```yaml {6} -components: - schemas: - MyUser: - _metadata: - type: object - x-fern-property-name: data -``` - -## Server names - -The `x-fern-server-name` extension is used to name your servers. - -```yaml title="openapi.yml" -servers: - - url: https://api.example.com - x-fern-server-name: Production - - url: https://sandbox.example.com - x-fern-server-name: Sandbox -``` - -In a generated TypeScript SDK, you'd see: - -```typescript title="environment.ts" -export const ExampleEnvironment = { - Production: "https://api.example.com" -} as const; - -export type ExampleEnvironment = typeof ExampleEnvironment.Production; -``` - -## Base path - -The `x-fern-base-path` extension is used to configure the base path prepended to every endpoint. - -In the example below, we have configured the `/v1` base path so the full endpoint path is -`https://api.example.com/v1/users`. - -```yaml title="Set the base path in openapi.yml" {1} -x-fern-base-path: /v1 -servers: - - url: https://api.example.com -paths: - /users: ... -``` - -## Ignoring schemas or endpoints - -If you want Fern to skip reading any endpoints or schemas, use the `x-fern-ignore` extension. - -To skip an endpoint, add `x-fern-ignore: true` at the operation level. - -```yaml title="x-fern-ignore at operation level in openapi.yml" {4} -paths: - /users: - get: - x-fern-ignore: true - ... -``` - -To skip a schema, add `x-fern-ignore: true` at the schema level. - -```yaml title="x-fern-ignore at schema level in openapi.yml" {4} -components: - schemas: - SchemaToSkip: - x-fern-ignore: true - ... -``` - -## Overlaying extensions - -Because of the number of tools that use OpenAPI, it may be more convenient to -"overlay" your fern specific OpenAPI extensions onto your original definition. \ -In order to do this you can specify your overrides file in `generators.yml`. - -Below is an example of how someone can overlay the extensions `x-fern-sdk-method-name` and -`x-fern-sdk-group-name` without polluting their original OpenAPI. The combined result is -shown in the third tab. - - - ```yaml title="generators.yml" {3} - api: - path: ./openapi/openapi.yaml - overrides: ./openapi/overrides.yaml - default-group: sdk - groups: - sdk: - generators: - - name: fernapi/fern-python-sdk - version: 2.2.0 - ``` - - ```yaml title="overrides.yml" - paths: - /users: - get: - x-fern-sdk-group-name: users - x-fern-sdk-method-name: get - ``` - - ```yaml title="Overlaid OpenAPI" {4-5} - paths: - /users: - get: - x-fern-sdk-group-name: users - x-fern-sdk-method-name: get - summary: Get a list of users - description: Retrieve a list of users from the system. - responses: - '200': - description: Successful response - '500': - description: Internal Server Error - ``` - - - -## Embedding extensions - -If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI Specifications make it easy to embed extensions directly from code. - -### FastAPI - -Please view our page on [FastAPI](/learn/api-definition/openapi/frameworks/fastapi) for more information on how to extend your OpenAPI Specification within FastAPI. - -## Request + response examples - -While OpenAPI has several fields for examples, there is no easy way -to associate a request with a response. This is especially useful when -you want to show more than one example in your documentation. - -`x-fern-examples` is an array of examples. Each element of the array -can contain `path-parameters`, `query-parameters`, `request` and `response` -examples values that are all associated. - -```yaml title="openapi.yml" {5-16} -paths: - /users/{userId}: - get: - x-fern-examples: - - path-parameters: - userId: user-1234 - response: - body: - name: Foo - ssn: 1234 - - path-parameters: - userId: user-4567 - response: - body: - name: Foo - ssn: 4567 -components: - schemas: - User: - type: object - properties: - name: - type: string - ssn: - type: integer -``` - -### Code samples - -If you'd like to specify custom code samples for your example, use `code-samples`. - -```yaml title="openapi.yml" {11-16} -paths: - /users/{userId}: - get: - x-fern-examples: - - path-parameters: - userId: user-1234 - response: - body: - name: Foo - ssn: 1234 - code-samples: - - sdk: typescript - code: | - import { UserClient } from "..."; - - client.users.get("user-1234") -``` - -If you're on the Fern Basic plan or higher for SDKs you won't have to worry about manually adding code samples! Our generators do that for you. - -## Availability - -The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags. - -The options are: - -- `beta` -- `generally-available` -- `deprecated` - -The example below marks that the `POST /pet` endpoint is `deprecated`. - -```yaml title="x-fern-availability in openapi.yml" {4} -paths: - /pet: - post: - x-fern-availability: deprecated -``` - -This renders as: - - -![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png) - - -### Request new extensions - -If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. diff --git a/fern/products/api-def/openapi-pages/extensions/overview.md b/fern/products/api-def/openapi-pages/extensions/overview.md new file mode 100644 index 000000000..9371758dd --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/overview.md @@ -0,0 +1,101 @@ +--- +title: Overview of OpenAPI extensions +description: Learn about Fern's OpenAPI extensions +--- +Fern supports a variety of OpenAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenAPI specification. + +## Available extensions + +The table below shows all available extensions and links to detailed documentation for each one. + +| Extension | Description | +| --- | --- | +| [`x-fern-version`](./api-version) | Configure API version schemes and headers | +| [`x-fern-audiences`](./audiences) | Filter endpoints, schemas, and properties by audience | +| [`x-fern-availability`](./availability) | Mark availability status (beta, generally-available, deprecated) | +| [`x-fern-base-path`](./base-path) | Set base path prepended to all endpoints | +| [`x-fern-enum`](./enums) | Add descriptions and custom names to enum values | +| [`x-fern-examples`](./examples) | Associate request and response examples | +| [`x-fern-global-headers`](./global-headers) | Configure headers used across all endpoints | +| [`x-fern-ignore`](./ignore) | Skip reading specific endpoints or schemas | +| [`x-fern-sdk-method-name`](./method-names) | Customize SDK method names | +| [`x-fern-sdk-group-name`](./method-names) | Organize methods into SDK groups | +| [`x-fern-parameter-name`](./parameter-names) | Customize parameter variable names | +| [`x-fern-property-name`](./property-names) | Customize object property variable names | +| [`x-fern-type-name`](./schema-names) | Override auto-generated names for inline schemas | +| [`x-fern-server-name`](./server-names) | Name your servers | + + + If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. + + +## Overlaying extensions + +Overlaying extensions allows you to keep your original OpenAPI specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your OpenAPI spec, or when you want to maintain a pristine source specification. + +To use overlays, specify an overrides file in your `generators.yml` configuration. + +The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original OpenAPI specification. + + + ```yaml title="generators.yml" {3} + api: + path: ./openapi/openapi.yaml + overrides: ./openapi/overrides.yaml + default-group: sdk + groups: + sdk: + generators: + - name: fernapi/fern-python-sdk + version: 2.2.0 + ``` + + ```yaml title="overrides.yml" {4-5} + paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: get + ``` + + ```yaml title="Overlaid OpenAPI" {4-5} + paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: get + summary: Get a list of users + description: Retrieve a list of users from the system. + responses: + '200': + description: Successful response + '500': + description: Internal Server Error + ``` + + + +## Embedding extensions + +Instead of using overlay files, you can embed Fern extensions directly within your OpenAPI specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions. + +### Direct embedding in OpenAPI + +You can add Fern extensions directly to your OpenAPI specification: + +```yaml title="openapi.yml" +paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: listUsers + x-fern-availability: generally-available + summary: Get a list of users + responses: + '200': + description: Successful response +``` + +### FastAPI + +FastAPI allows you to add extensions directly in your route decorators and models. See our [FastAPI integration guide](/api-definition/openapi/frameworks/fastapi) for detailed examples. diff --git a/fern/products/api-def/openapi-pages/extensions/property-names.mdx b/fern/products/api-def/openapi-pages/extensions/property-names.mdx new file mode 100644 index 000000000..e37da2f6d --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/property-names.mdx @@ -0,0 +1,19 @@ +--- +title: Property names +description: Customize variable names for object properties using the `x-fern-property-name` extension +--- + +The `x-fern-property-name` extension allows you to customize the variable name for object +properties. + +For example, if you had a property called `_metadata` in your schema but you wanted the +variable to be called `data` in your SDK you would do the following: + +```yaml {6} +components: + schemas: + MyUser: + _metadata: + type: object + x-fern-property-name: data +``` \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/extensions/schema-names.mdx b/fern/products/api-def/openapi-pages/extensions/schema-names.mdx new file mode 100644 index 000000000..75e85feb9 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/schema-names.mdx @@ -0,0 +1,82 @@ +--- +title: Schema names +description: Override auto-generated names for inline schemas using the `x-fern-type-name` extension +--- + +OpenAPI allows you to define inlined schemas that do not have names. + +```yaml title="Inline type in openapi.yml" {11} +components: + schemas: + Movie: + type: object + properties: + name: + type: string + cast: + type: array + items: + type: object + properties: + firstName: + type: string + lastName: + type: string + age: + type: integer +``` + +Fern automatically generates names for all the inlined schemas. For example, in this example, +Fern would generate the name `CastItem` for the inlined array item schema. + +```typescript title="Auto-generated name" {6} +export interface Movie { + name?: string; + cast?: CastItem[]; +} + +export interface CastItem { + firstName?: string; + lastName?: string; + age?: integer; +} +``` + +If you want to override the generated name, you can use the extension `x-fern-type-name`. + +```yaml title="openapi.yml" {12} +components: + schemas: + Movie: + type: object + properties: + name: + type: string + cast: + type: array + items: + type: object + x-fern-type-name: Person + properties: + firstName: + type: string + lastName: + type: string + age: + type: integer +``` + +This would replace `CastItem` with `Person` and the generated code would read more idiomatically: + +```typescript title="Overridden name" {6} +export interface Movie { + name?: string; + cast?: Person[]; +} + +export interface Person { + firstName?: string; + lastName?: string; + age?: integer; +} +``` diff --git a/fern/products/api-def/openapi-pages/extensions/server-names.mdx b/fern/products/api-def/openapi-pages/extensions/server-names.mdx new file mode 100644 index 000000000..a5f2c1596 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/server-names.mdx @@ -0,0 +1,25 @@ + +--- +title: Server names +description: Name your servers using the `x-fern-server-name` extension +--- + +The `x-fern-server-name` extension is used to name your servers. + +```yaml title="openapi.yml" +servers: + - url: https://api.example.com + x-fern-server-name: Production + - url: https://sandbox.example.com + x-fern-server-name: Sandbox +``` + +In a generated TypeScript SDK, you'd see: + +```typescript title="environment.ts" +export const ExampleEnvironment = { + Production: "https://api.example.com" +} as const; + +export type ExampleEnvironment = typeof ExampleEnvironment.Production; +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/availability.mdx b/fern/products/api-def/openrpc-pages/extensions/availability.mdx new file mode 100644 index 000000000..218d9fa71 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/availability.mdx @@ -0,0 +1,23 @@ +--- +title: Availability +description: Mark features as available in specific SDK versions using `x-fern-availability` extension +--- + +Mark features as available in specific SDK versions: + +```yaml title="openrpc.yml" {4-6} +methods: + - name: beta.advancedSearch + summary: Advanced search functionality + x-fern-availability: + status: beta + message: "This feature is in beta and may change" + params: + - name: searchQuery + schema: + $ref: '#/components/schemas/AdvancedSearchQuery' + result: + name: searchResults + schema: + $ref: '#/components/schemas/SearchResults' +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/base-path.mdx b/fern/products/api-def/openrpc-pages/extensions/base-path.mdx new file mode 100644 index 000000000..22cb0d7bb --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/base-path.mdx @@ -0,0 +1,14 @@ +--- +title: Base path +description: Configure base paths for generated SDK clients using `x-fern-base-path` extension +--- + +Configure base paths for generated SDK clients: + +```yaml title="openrpc.yml" {3-4} +info: + title: My JSON-RPC API + version: 1.0.0 + x-fern-base-path: /api/v1/rpc + description: JSON-RPC API with custom base path +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/error-handling.mdx b/fern/products/api-def/openrpc-pages/extensions/error-handling.mdx new file mode 100644 index 000000000..41c4297e6 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/error-handling.mdx @@ -0,0 +1,31 @@ +--- +title: Error handling +description: Configure error handling for methods using `x-fern-error-handling` extension +--- + +Configure error handling for methods: + +```yaml title="openrpc.yml" {10-20} +methods: + - name: order.create + summary: Create a new order + params: + - name: orderData + schema: + $ref: '#/components/schemas/CreateOrderRequest' + errors: + - code: -32001 + message: Insufficient inventory + x-fern-error-handling: + error_name: InsufficientInventoryError + retry_after_seconds: 60 + - code: -32002 + message: Payment failed + x-fern-error-handling: + error_name: PaymentFailedError + user_friendly_message: "Payment could not be processed. Please check your payment information." + result: + name: order + schema: + $ref: '#/components/schemas/Order' +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/examples.mdx b/fern/products/api-def/openrpc-pages/extensions/examples.mdx new file mode 100644 index 000000000..aa6676337 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Request + response examples +description: Provide additional examples for better SDK documentation using `x-fern-examples` extension +--- + +Provide additional examples for better SDK documentation: + +```yaml title="openrpc.yml" {8-25} +methods: + - name: user.create + summary: Create a new user + params: + - name: userData + schema: + $ref: '#/components/schemas/CreateUserRequest' + required: true + x-fern-examples: + - name: StandardUser + description: Create a regular user account + params: + userData: + email: "john@example.com" + name: "John Doe" + role: "user" + result: + id: "user_123" + email: "john@example.com" + name: "John Doe" + role: "user" + createdAt: "2024-01-15T10:30:00Z" + - name: AdminUser + description: Create an admin user account + params: + userData: + email: "admin@example.com" + name: "Admin User" + role: "admin" + permissions: ["read", "write", "delete"] + result: + id: "user_456" + email: "admin@example.com" + name: "Admin User" + role: "admin" + createdAt: "2024-01-15T10:30:00Z" + result: + name: user + schema: + $ref: '#/components/schemas/User' +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/ignore.mdx b/fern/products/api-def/openrpc-pages/extensions/ignore.mdx new file mode 100644 index 000000000..59df1f37c --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/ignore.mdx @@ -0,0 +1,29 @@ +--- +title: Ignoring methods or schemas +description: Skip reading specific OpenRPC elements using `x-fern-ignore` extension +--- + +Use `x-fern-ignore` to exclude specific methods or schemas from SDK generation: + +```yaml title="openrpc.yml" {4-5, 12-13} +methods: + - name: debug.internalMethod + summary: Internal debugging method + x-fern-ignore: true + params: + - name: debugData + schema: + type: object + result: + name: debugResult + schema: + type: object + - name: test.experimentalFeature + summary: Experimental feature (not ready for public use) + x-fern-ignore: true + params: [] + result: + name: result + schema: + type: string +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/others.mdx b/fern/products/api-def/openrpc-pages/extensions/others.mdx deleted file mode 100644 index 365ae0461..000000000 --- a/fern/products/api-def/openrpc-pages/extensions/others.mdx +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: Other Extensions -subtitle: Additional Fern extensions for OpenRPC specifications ---- - -Fern supports various extensions to enhance your OpenRPC specifications and improve the generated SDKs and documentation. - -## `x-fern-ignore` - -Use `x-fern-ignore` to exclude specific methods or schemas from SDK generation: - -```yaml title="openrpc.yml" {4-5, 12-13} -methods: - - name: debug.internalMethod - summary: Internal debugging method - x-fern-ignore: true - params: - - name: debugData - schema: - type: object - result: - name: debugResult - schema: - type: object - - name: test.experimentalFeature - summary: Experimental feature (not ready for public use) - x-fern-ignore: true - params: [] - result: - name: result - schema: - type: string -``` - -## `x-fern-examples` - -Provide additional examples for better SDK documentation: - -```yaml title="openrpc.yml" {8-25} -methods: - - name: user.create - summary: Create a new user - params: - - name: userData - schema: - $ref: '#/components/schemas/CreateUserRequest' - required: true - x-fern-examples: - - name: StandardUser - description: Create a regular user account - params: - userData: - email: "john@example.com" - name: "John Doe" - role: "user" - result: - id: "user_123" - email: "john@example.com" - name: "John Doe" - role: "user" - createdAt: "2024-01-15T10:30:00Z" - - name: AdminUser - description: Create an admin user account - params: - userData: - email: "admin@example.com" - name: "Admin User" - role: "admin" - permissions: ["read", "write", "delete"] - result: - id: "user_456" - email: "admin@example.com" - name: "Admin User" - role: "admin" - createdAt: "2024-01-15T10:30:00Z" - result: - name: user - schema: - $ref: '#/components/schemas/User' -``` - -## `x-fern-pagination` - -Configure pagination for methods that return multiple results: - -```yaml title="openrpc.yml" {6-11} -methods: - - name: user.list - summary: List users with pagination - params: - - name: pagination - schema: - type: object - properties: - cursor: - type: string - limit: - type: integer - default: 20 - x-fern-pagination: - cursor: pagination.cursor - results: users - next_cursor: pagination.nextCursor - has_next_page: pagination.hasMore - result: - name: userList - schema: - type: object - properties: - users: - type: array - items: - $ref: '#/components/schemas/User' - pagination: - type: object - properties: - nextCursor: - type: string - hasMore: - type: boolean -``` - -## `x-fern-retry` - -Configure retry behavior for methods: - -```yaml title="openrpc.yml" {6-10} -methods: - - name: payment.process - summary: Process payment with retry logic - params: - - name: paymentData - schema: - $ref: '#/components/schemas/PaymentRequest' - x-fern-retry: - max_attempts: 3 - exponential_backoff: true - initial_delay: 1000 - max_delay: 30000 - result: - name: paymentResult - schema: - $ref: '#/components/schemas/PaymentResult' -``` - -## `x-fern-timeout` - -Configure timeout settings for methods: - -```yaml title="openrpc.yml" {6-8} -methods: - - name: report.generate - summary: Generate large report (may take time) - params: - - name: reportConfig - schema: - $ref: '#/components/schemas/ReportConfig' - x-fern-timeout: - seconds: 300 - description: "Report generation can take up to 5 minutes" - result: - name: report - schema: - $ref: '#/components/schemas/Report' -``` - -## `x-fern-error-handling` - -Configure error handling for methods: - -```yaml title="openrpc.yml" {10-20} -methods: - - name: order.create - summary: Create a new order - params: - - name: orderData - schema: - $ref: '#/components/schemas/CreateOrderRequest' - errors: - - code: -32001 - message: Insufficient inventory - x-fern-error-handling: - error_name: InsufficientInventoryError - retry_after_seconds: 60 - - code: -32002 - message: Payment failed - x-fern-error-handling: - error_name: PaymentFailedError - user_friendly_message: "Payment could not be processed. Please check your payment information." - result: - name: order - schema: - $ref: '#/components/schemas/Order' -``` - -## `x-fern-availability` - -Mark features as available in specific SDK versions: - -```yaml title="openrpc.yml" {4-6} -methods: - - name: beta.advancedSearch - summary: Advanced search functionality - x-fern-availability: - status: beta - message: "This feature is in beta and may change" - params: - - name: searchQuery - schema: - $ref: '#/components/schemas/AdvancedSearchQuery' - result: - name: searchResults - schema: - $ref: '#/components/schemas/SearchResults' -``` - -## `x-fern-streaming` - -Mark methods as streaming for appropriate SDK generation: - -```yaml title="openrpc.yml" {4-6} -methods: - - name: logs.stream - summary: Stream log events - x-fern-streaming: - type: server_sent_events - termination: client_closes - params: - - name: filters - schema: - type: object - properties: - level: - type: string - enum: [debug, info, warn, error] - service: - type: string - # Note: Streaming methods typically don't have a traditional result -``` - -## `x-fern-server-name` - -Specify custom names for servers: - -```yaml title="openrpc.yml" {3-4} -servers: - - name: production - url: https://api.yourcompany.com/rpc - x-fern-server-name: Production - description: Production JSON-RPC server - - name: staging - url: https://staging-api.yourcompany.com/rpc - x-fern-server-name: Staging - description: Staging environment -``` - -## `x-fern-base-path` - -Configure base paths for generated SDK clients: - -```yaml title="openrpc.yml" {3-4} -info: - title: My JSON-RPC API - version: 1.0.0 - x-fern-base-path: /api/v1/rpc - description: JSON-RPC API with custom base path -``` - -## `x-fern-sdk-group-name` - -Group related methods in the SDK: - -```yaml title="openrpc.yml" {4-5, 12-13} -methods: - - name: user.create - summary: Create user - x-fern-sdk-group-name: users - params: [...] - result: {...} - - - name: user.get - summary: Get user - x-fern-sdk-group-name: users - params: [...] - result: {...} - - - name: order.create - summary: Create order - x-fern-sdk-group-name: orders - params: [...] - result: {...} -``` - -This generates SDKs with grouped methods: - -```typescript -client.users.create(...) -client.users.get(...) -client.orders.create(...) -``` - -These extensions help you create more robust and user-friendly SDKs while maintaining full control over the generated code structure and behavior. \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/overview.md b/fern/products/api-def/openrpc-pages/extensions/overview.md new file mode 100644 index 000000000..9993f386d --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/overview.md @@ -0,0 +1,28 @@ +--- +title: Overview of OpenRPC extensions +description: Learn about Fern's OpenRPC extensions for generating higher-quality SDKs +--- + +Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs. + +The table below shows all available extensions and links to detailed documentation for each one. + +## Available extensions + +| Extension | Description | +| --- | --- | +| [`x-fern-ignore`](./ignore) | Skip reading specific methods or schemas | +| [`x-fern-examples`](./examples) | Provide additional examples for better SDK documentation | +| [`x-fern-pagination`](./pagination) | Configure pagination for methods that return multiple results | +| [`x-fern-retry`](./retry) | Configure retry behavior for methods | +| [`x-fern-timeout`](./timeout) | Configure timeout settings for methods | +| [`x-fern-error-handling`](./error-handling) | Configure error handling for methods | +| [`x-fern-availability`](./availability) | Mark features as available in specific SDK versions | +| [`x-fern-streaming`](./streaming) | Mark methods as streaming for appropriate SDK generation | +| [`x-fern-server-name`](./server-name) | Specify custom names for servers | +| [`x-fern-base-path`](./base-path) | Configure base paths for generated SDK clients | +| [`x-fern-sdk-group-name`](./sdk-group-name) | Group related methods in the SDK | + + + If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. + \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/pagination.mdx b/fern/products/api-def/openrpc-pages/extensions/pagination.mdx new file mode 100644 index 000000000..8b26b2131 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/pagination.mdx @@ -0,0 +1,43 @@ +--- +title: Pagination +description: Configure pagination for methods that return multiple results using `x-fern-pagination` extension +--- + +Configure pagination for methods that return multiple results: + +```yaml title="openrpc.yml" {6-11} +methods: + - name: user.list + summary: List users with pagination + params: + - name: pagination + schema: + type: object + properties: + cursor: + type: string + limit: + type: integer + default: 20 + x-fern-pagination: + cursor: pagination.cursor + results: users + next_cursor: pagination.nextCursor + has_next_page: pagination.hasMore + result: + name: userList + schema: + type: object + properties: + users: + type: array + items: + $ref: '#/components/schemas/User' + pagination: + type: object + properties: + nextCursor: + type: string + hasMore: + type: boolean +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/retry.mdx b/fern/products/api-def/openrpc-pages/extensions/retry.mdx new file mode 100644 index 000000000..ee4083dba --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/retry.mdx @@ -0,0 +1,25 @@ +--- +title: Retry behavior +description: Configure retry behavior for methods using `x-fern-retry` extension +--- + +Configure retry behavior for methods: + +```yaml title="openrpc.yml" {6-10} +methods: + - name: payment.process + summary: Process payment with retry logic + params: + - name: paymentData + schema: + $ref: '#/components/schemas/PaymentRequest' + x-fern-retry: + max_attempts: 3 + exponential_backoff: true + initial_delay: 1000 + max_delay: 30000 + result: + name: paymentResult + schema: + $ref: '#/components/schemas/PaymentResult' +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/sdk-group-name.mdx b/fern/products/api-def/openrpc-pages/extensions/sdk-group-name.mdx new file mode 100644 index 000000000..9e2107014 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/sdk-group-name.mdx @@ -0,0 +1,35 @@ +--- +title: SDK group names +description: Group related methods in the SDK using `x-fern-sdk-group-name` extension +--- + +Group related methods in the SDK: + +```yaml title="openrpc.yml" {4-5, 12-13} +methods: + - name: user.create + summary: Create user + x-fern-sdk-group-name: users + params: [...] + result: {...} + + - name: user.get + summary: Get user + x-fern-sdk-group-name: users + params: [...] + result: {...} + + - name: order.create + summary: Create order + x-fern-sdk-group-name: orders + params: [...] + result: {...} +``` + +This generates SDKs with grouped methods: + +```typescript +client.users.create(...) +client.users.get(...) +client.orders.create(...) +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/server-name.mdx b/fern/products/api-def/openrpc-pages/extensions/server-name.mdx new file mode 100644 index 000000000..d8d127b3a --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/server-name.mdx @@ -0,0 +1,18 @@ +--- +title: Server names +description: Specify custom names for servers using `x-fern-server-name` extension +--- + +Specify custom names for servers: + +```yaml title="openrpc.yml" {3-4} +servers: + - name: production + url: https://api.yourcompany.com/rpc + x-fern-server-name: Production + description: Production JSON-RPC server + - name: staging + url: https://staging-api.yourcompany.com/rpc + x-fern-server-name: Staging + description: Staging environment +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/streaming.mdx b/fern/products/api-def/openrpc-pages/extensions/streaming.mdx new file mode 100644 index 000000000..305d3ec65 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/streaming.mdx @@ -0,0 +1,26 @@ +--- +title: Streaming operations +description: Mark methods as streaming for appropriate SDK generation using `x-fern-streaming` extension +--- + +Mark methods as streaming for appropriate SDK generation: + +```yaml title="openrpc.yml" {4-6} +methods: + - name: logs.stream + summary: Stream log events + x-fern-streaming: + type: server_sent_events + termination: client_closes + params: + - name: filters + schema: + type: object + properties: + level: + type: string + enum: [debug, info, warn, error] + service: + type: string + # Note: Streaming methods typically don't have a traditional result +``` \ No newline at end of file diff --git a/fern/products/api-def/openrpc-pages/extensions/timeout.mdx b/fern/products/api-def/openrpc-pages/extensions/timeout.mdx new file mode 100644 index 000000000..d1979fa84 --- /dev/null +++ b/fern/products/api-def/openrpc-pages/extensions/timeout.mdx @@ -0,0 +1,23 @@ +--- +title: Timeout settings +description: Configure timeout settings for methods using `x-fern-timeout` extension +--- + +Configure timeout settings for methods: + +```yaml title="openrpc.yml" {6-8} +methods: + - name: report.generate + summary: Generate large report (may take time) + params: + - name: reportConfig + schema: + $ref: '#/components/schemas/ReportConfig' + x-fern-timeout: + seconds: 300 + description: "Report generation can take up to 5 minutes" + result: + name: report + schema: + $ref: '#/components/schemas/Report' +``` \ No newline at end of file From dea47430a4cacdbc6f87c8d9729e350a19500237 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 14 Aug 2025 14:35:45 -0400 Subject: [PATCH 2/2] add overlay/embed info to asyncapi and openrpc --- fern/products/api-def/api-def.yml | 8 +-- .../asyncapi-pages/extensions/overview.md | 6 +- .../openapi-pages/extensions/overview.md | 67 +------------------ .../openrpc-pages/extensions/overview.md | 10 +-- fern/snippets/overlay-embed-extensions.mdx | 66 ++++++++++++++++++ 5 files changed, 81 insertions(+), 76 deletions(-) create mode 100644 fern/snippets/overlay-embed-extensions.mdx diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 509ddb0d6..f55634a21 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -48,7 +48,7 @@ navigation: path: ./openapi-pages/extensions/examples.mdx - page: Global headers path: ./openapi-pages/extensions/global-headers.mdx - - page: Ignoring schemas or endpoints + - page: Ignoring elements path: ./openapi-pages/extensions/ignore.mdx - page: SDK method names path: ./openapi-pages/extensions/method-names.mdx @@ -109,7 +109,7 @@ navigation: path: ./asyncapi-pages/extensions/error-handling.mdx - page: Request + response examples path: ./asyncapi-pages/extensions/examples.mdx - - page: Ignoring operations, channels, or schemas + - page: Ignoring elements path: ./asyncapi-pages/extensions/ignore.mdx - page: SDK method names path: ./asyncapi-pages/extensions/method-names.mdx @@ -168,7 +168,7 @@ navigation: path: ./openrpc-pages/extensions/error-handling.mdx - page: Request + response examples path: ./openrpc-pages/extensions/examples.mdx - - page: Ignoring methods or schemas + - page: Ignoring elements path: ./openrpc-pages/extensions/ignore.mdx - page: SDK method names path: ./openrpc-pages/extensions/method-names.mdx @@ -231,7 +231,7 @@ navigation: path: ./grpc-pages/extensions/error-handling.mdx - page: Request + response examples path: ./grpc-pages/extensions/examples.mdx - - page: Ignoring services, methods, or messages + - page: Ignoring elements path: ./grpc-pages/extensions/ignore.mdx - page: SDK method names path: ./grpc-pages/extensions/method-names.mdx diff --git a/fern/products/api-def/asyncapi-pages/extensions/overview.md b/fern/products/api-def/asyncapi-pages/extensions/overview.md index 71d836ff7..434c43b2e 100644 --- a/fern/products/api-def/asyncapi-pages/extensions/overview.md +++ b/fern/products/api-def/asyncapi-pages/extensions/overview.md @@ -3,7 +3,7 @@ title: Overview of AsyncAPI extensions description: Learn about Fern's AsyncAPI extensions for generating higher-quality SDKs --- -Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. +Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your AsyncAPI specification. ## Available extensions @@ -22,4 +22,6 @@ The table below shows all available extensions and links to detailed documentati If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. - \ No newline at end of file + + + \ No newline at end of file diff --git a/fern/products/api-def/openapi-pages/extensions/overview.md b/fern/products/api-def/openapi-pages/extensions/overview.md index 9371758dd..93e741f89 100644 --- a/fern/products/api-def/openapi-pages/extensions/overview.md +++ b/fern/products/api-def/openapi-pages/extensions/overview.md @@ -29,72 +29,7 @@ The table below shows all available extensions and links to detailed documentati If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. -## Overlaying extensions - -Overlaying extensions allows you to keep your original OpenAPI specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your OpenAPI spec, or when you want to maintain a pristine source specification. - -To use overlays, specify an overrides file in your `generators.yml` configuration. - -The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original OpenAPI specification. - - - ```yaml title="generators.yml" {3} - api: - path: ./openapi/openapi.yaml - overrides: ./openapi/overrides.yaml - default-group: sdk - groups: - sdk: - generators: - - name: fernapi/fern-python-sdk - version: 2.2.0 - ``` - - ```yaml title="overrides.yml" {4-5} - paths: - /users: - get: - x-fern-sdk-group-name: users - x-fern-sdk-method-name: get - ``` - - ```yaml title="Overlaid OpenAPI" {4-5} - paths: - /users: - get: - x-fern-sdk-group-name: users - x-fern-sdk-method-name: get - summary: Get a list of users - description: Retrieve a list of users from the system. - responses: - '200': - description: Successful response - '500': - description: Internal Server Error - ``` - - - -## Embedding extensions - -Instead of using overlay files, you can embed Fern extensions directly within your OpenAPI specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions. - -### Direct embedding in OpenAPI - -You can add Fern extensions directly to your OpenAPI specification: - -```yaml title="openapi.yml" -paths: - /users: - get: - x-fern-sdk-group-name: users - x-fern-sdk-method-name: listUsers - x-fern-availability: generally-available - summary: Get a list of users - responses: - '200': - description: Successful response -``` + ### FastAPI diff --git a/fern/products/api-def/openrpc-pages/extensions/overview.md b/fern/products/api-def/openrpc-pages/extensions/overview.md index 9993f386d..9170839b0 100644 --- a/fern/products/api-def/openrpc-pages/extensions/overview.md +++ b/fern/products/api-def/openrpc-pages/extensions/overview.md @@ -3,12 +3,12 @@ title: Overview of OpenRPC extensions description: Learn about Fern's OpenRPC extensions for generating higher-quality SDKs --- -Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs. - -The table below shows all available extensions and links to detailed documentation for each one. +Fern supports a variety of OpenRPC extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your OpenRPC specification. ## Available extensions +The table below shows all available extensions and links to detailed documentation for each one. + | Extension | Description | | --- | --- | | [`x-fern-ignore`](./ignore) | Skip reading specific methods or schemas | @@ -25,4 +25,6 @@ The table below shows all available extensions and links to detailed documentati If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. - \ No newline at end of file + + + \ No newline at end of file diff --git a/fern/snippets/overlay-embed-extensions.mdx b/fern/snippets/overlay-embed-extensions.mdx new file mode 100644 index 000000000..5021439ca --- /dev/null +++ b/fern/snippets/overlay-embed-extensions.mdx @@ -0,0 +1,66 @@ +## Overlaying extensions + +Overlaying extensions allows you to keep your original API specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you're using multiple tools that consume your API spec, or when you want to maintain a pristine source specification. + +To use overlays, specify an overrides file in your `generators.yml` configuration. + +The example below shows how to overlay SDK naming extensions. The first tab shows the `generators.yml` configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original API specification. + + + ```yaml title="generators.yml" {3} + api: + path: ./spec-folder/spec-file.yaml + overrides: ./spec-folder/overrides.yaml # Reference your overrides file + default-group: sdk + groups: + sdk: + generators: + - name: fernapi/fern-python-sdk + version: 2.2.0 + ``` + + ```yaml title="overrides.yml" {4-5} + paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: get + ``` + + ```yaml title="Overlaid spec" {4-5} + paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: get + summary: Get a list of users + description: Retrieve a list of users from the system. + responses: + '200': + description: Successful response + '500': + description: Internal Server Error + ``` + + + +## Embedding extensions + +Instead of using overlay files, you can embed Fern extensions directly within your API specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions. + +### Direct embedding + +You can add Fern extensions directly to your API specification: + +```yaml title="spec-file.yml" {4-6} +paths: + /users: + get: + x-fern-sdk-group-name: users + x-fern-sdk-method-name: listUsers + x-fern-availability: generally-available + summary: Get a list of users + responses: + '200': + description: Successful response +``` \ No newline at end of file