feat: playground settings

fern/apis/navigation/definition/__package__.yml

@@ -8,6 +8,9 @@ types:
   TabId: string
   PageId: string
   NodeId: string
+  EnvironmentId:
+    type: string
+    docs: Identifier for an API environment (i.e. "Prod", "Staging", "Dev")
 
   ApiDefinitionId: string
   EndpointId: string
@@ -203,11 +206,30 @@ types:
       - WithRedirect
     properties:
       type: literal<"apiReference">
-      disableLongScrolling: optional<boolean>
+      paginated:
+        type: optional<boolean>
+        docs: If true, long-scrolling will be disabled.
       showErrors: optional<boolean>
       hideTitle: optional<boolean>
       children: list<ApiPackageChild>
       changelog: optional<ChangelogNode>
+      playground:
+        type: optional<PlaygroundSettings>
+        docs: Settings for the api playground that affects all endpoints.
+
+  PlaygroundSettings:
+    properties:
+      # enabled: optional<boolean> (this is currently controlled in feature flags)
+      allowedEnvironments:
+        type: optional<list<EnvironmentId>>
+        docs: |
+          A list of environment IDs that are allowed to be used in the playground.
+          If not provided, all environments are allowed. And if the provided list is empty, the playground should be disabled.
+      button: optional<PlaygroundButtonSettings>
+
+  PlaygroundButtonSettings:
+    properties:
+      href: optional<Url>
 
   EndpointNode:
     extends:
@@ -218,6 +240,9 @@ types:
       method: HttpMethod
       endpointId: EndpointId
       isResponseStream: optional<boolean>
+      playground:
+        type: optional<PlaygroundSettings>
+        docs: Settings for the api playground that affect this endpoint specifically.
 
   WebSocketNode:
     extends:
@@ -226,6 +251,9 @@ types:
     properties:
       type: literal<"webSocket">
       webSocketId: WebSocketId
+      playground:
+        type: optional<PlaygroundSettings>
+        docs: Settings for the api playground that affect this endpoint specifically.
 
   WebhookNode:
     extends:
@@ -235,6 +263,7 @@ types:
       type: literal<"webhook">
       method: HttpMethod
       webhookId: WebhookId
+      # note: webhooks do not have a playground
 
   ApiPackageNode:
     extends:
@@ -245,6 +274,9 @@ types:
     properties:
       type: literal<"apiPackage">
       children: list<ApiPackageChild>
+      playground:
+        type: optional<PlaygroundSettings>
+        docs: Settings for the api playground that affects all endpoints.
 
   # utilities
 

packages/fdr-sdk/src/navigation/__test__/__snapshots__/primer.test.ts.snap

@@ -980,7 +980,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/introdu
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -1077,7 +1077,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/introdu
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -1416,7 +1416,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/introdu
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -1504,7 +1504,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/introdu
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -1817,7 +1817,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/introdu
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -2689,7 +2689,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/v2.1/ap
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -2786,7 +2786,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/v2.1/ap
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -3125,7 +3125,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/v2.1/ap
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -3213,7 +3213,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/v2.1/ap
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,
@@ -3526,7 +3526,7 @@ exports[`getNavigationRoot > primer > gets navigation root for /docs/api/v2.1/ap
               "type": "apiPackage",
             },
           ],
-          "disableLongScrolling": undefined,
+          "paginated": undefined,
           "hidden": undefined,
           "hideTitle": undefined,
           "icon": undefined,

packages/fdr-sdk/src/navigation/converters/ApiReferenceNavigationConverter.ts

@@ -21,7 +21,7 @@ export class ApiReferenceNavigationConverter {
         idgen?: NodeIdGenerator,
         lexicographic?: boolean,
         disableEndpointPairs?: boolean,
-        disableLongScrolling?: boolean,
+        paginated?: boolean,
     ) {
         return new ApiReferenceNavigationConverter(
             apiSection,
@@ -31,7 +31,7 @@ export class ApiReferenceNavigationConverter {
             idgen ?? new NodeIdGenerator(),
             lexicographic,
             disableEndpointPairs,
-            disableLongScrolling,
+            paginated,
         ).convert();
     }
 
@@ -50,7 +50,7 @@ export class ApiReferenceNavigationConverter {
         idgen: NodeIdGenerator,
         private lexicographic: boolean = false,
         private disableEndpointPairs: boolean = false,
-        private disableLongScrolling: boolean | undefined,
+        private paginated: boolean | undefined,
     ) {
         this.apiDefinitionId = FernNavigation.ApiDefinitionId(api.id);
         this.#holder = ApiDefinitionHolder.create(api);
@@ -84,8 +84,7 @@ export class ApiReferenceNavigationConverter {
                 apiDefinitionId: FernNavigation.ApiDefinitionId(this.apiSection.api),
                 overviewPageId,
                 noindex,
-                disableLongScrolling:
-                    this.disableLongScrolling ?? (this.apiSection.longScrolling === false ? true : undefined),
+                paginated: this.paginated ?? (this.apiSection.longScrolling === false ? true : undefined),
                 slug: slug.get(),
                 icon: this.apiSection.icon,
                 hidden: this.apiSection.hidden,
@@ -95,6 +94,7 @@ export class ApiReferenceNavigationConverter {
                 children,
                 availability: undefined,
                 pointsTo,
+                playground: undefined,
             };
         });
     }
@@ -125,6 +125,7 @@ export class ApiReferenceNavigationConverter {
                 apiDefinitionId: this.apiDefinitionId,
                 availability: convertAvailability(endpoint.availability),
                 isResponseStream: endpoint.response?.type.type === "stream",
+                playground: undefined,
             };
         });
     }
@@ -144,6 +145,7 @@ export class ApiReferenceNavigationConverter {
             hidden: undefined,
             apiDefinitionId: this.apiDefinitionId,
             availability: convertAvailability(webSocket.availability),
+            playground: undefined,
         }));
     }
 
@@ -240,6 +242,7 @@ export class ApiReferenceNavigationConverter {
                     availability: undefined,
                     apiDefinitionId: this.apiDefinitionId,
                     pointsTo,
+                    playground: undefined,
                 };
             });
             if (child != null) {
@@ -371,6 +374,7 @@ export class ApiReferenceNavigationConverter {
                             availability: undefined,
                             apiDefinitionId: this.apiDefinitionId,
                             pointsTo: followRedirects(convertedItems),
+                            playground: undefined,
                         });
                     });
                 },

packages/fdr-sdk/src/navigation/converters/NavigationConfigConverter.ts

@@ -19,7 +19,7 @@ export class NavigationConfigConverter {
         private basePath: string | undefined,
         private lexicographic?: boolean,
         private disableEndpointPairs?: boolean,
-        private disableLongScrolling?: boolean,
+        private paginated?: boolean,
     ) {}
 
     public static convert(
@@ -30,7 +30,7 @@ export class NavigationConfigConverter {
         basePath: string | undefined,
         lexicographic?: boolean,
         disableEndpointPairs?: boolean,
-        disableLongScrolling?: boolean,
+        paginated?: boolean,
     ): FernNavigation.RootNode {
         return new NavigationConfigConverter(
             title,
@@ -40,7 +40,7 @@ export class NavigationConfigConverter {
             basePath,
             lexicographic,
             disableEndpointPairs,
-            disableLongScrolling,
+            paginated,
         ).convert();
     }
 
@@ -292,16 +292,16 @@ export class NavigationConfigConverter {
                     this.#idgen,
                     this.lexicographic,
                     this.disableEndpointPairs,
-                    this.disableLongScrolling,
+                    this.paginated,
                 );
             },
             changelog: (changelog) =>
                 ChangelogNavigationConverter.convert(changelog, this.noindexMap, parentSlug, this.#idgen),
             // Note: apiSection.node is imported from `navigation`, and is guaranteed to be a FernNavigation.ApiReferenceNode
             apiV2: (apiSection) => {
                 const node = apiSection.node as unknown as FernNavigation.ApiReferenceNode;
-                if (this.disableLongScrolling) {
-                    node.disableLongScrolling = true;
+                if (this.paginated) {
+                    node.paginated = true;
                 }
                 return node;
             },