Reorganize extensions sections (API Definitions) (#450)

Author: devalog

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

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 elements
+            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 elements
+            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 elements
+            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 elements
+            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

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"
+```

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
+```