@gitbook/react-openapi 1.3.6 → 1.4.1

package/dist/types.d.ts

@@ -1,12 +1,21 @@
-import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
-export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & {
+import type { OpenAPICustomOperationProperties, OpenAPICustomPrefillProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
+export type OpenAPIServerVariableWithCustomProperties = OpenAPIV3.ServerVariableObject & OpenAPICustomPrefillProperties;
+/**
+ * OpenAPI ServerObject type extended to provide x-gitbook prefill custom properties at the variable level.
+ */
+export type OpenAPIServerWithCustomProperties = Omit<OpenAPIV3.ServerObject, 'variables'> & {
+    variables?: {
+        [variable: string]: OpenAPIServerVariableWithCustomProperties;
+    };
+} & OpenAPICustomPrefillProperties;
+export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & OpenAPICustomPrefillProperties & {
     required?: boolean;
 };
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     path: string;
     method: string;
     /** Servers to be used for this operation */
-    servers: OpenAPIV3.ServerObject[];
+    servers: OpenAPIServerWithCustomProperties[];
     /** Spec of the operation */
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
     /** Securities that should be used for this operation */

package/dist/util/tryit-prefill.d.ts

@@ -0,0 +1,20 @@
+import type { ApiClientConfiguration } from '@scalar/types';
+import type { PrefillInputContextData } from '../OpenAPIPrefillContextProvider';
+import type { OpenAPIOperationData } from '../types';
+export interface TryItPrefillConfiguration {
+    authentication?: ApiClientConfiguration['authentication'];
+    servers?: ApiClientConfiguration['servers'];
+}
+/**
+ * Resolve the Scalar API client prefill configuration for a given OpenAPI operation.
+ */
+export declare function resolveTryItPrefillForOperation(args: {
+    /**
+     * The parsed OpenAPI operation.
+     */
+    operation: Pick<OpenAPIOperationData, 'securities' | 'servers'>;
+    /**
+     * Prefill input context data.
+     */
+    prefillInputContext: PrefillInputContextData | null;
+}): TryItPrefillConfiguration;

package/dist/util/tryit-prefill.js

@@ -0,0 +1,129 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { ExpressionRuntime, parseTemplate } from '@gitbook/expr';
+/**
+ * Resolve the Scalar API client prefill configuration for a given OpenAPI operation.
+ */
+export function resolveTryItPrefillForOperation(args) {
+    var _a = args.operation, securities = _a.securities, servers = _a.servers, prefillInputContext = args.prefillInputContext;
+    if (!prefillInputContext) {
+        return {};
+    }
+    var runtime = new ExpressionRuntime();
+    var resolveTryItPrefillExpression = function (expr) {
+        var parts = parseTemplate(expr);
+        if (!parts.length) {
+            return undefined;
+        }
+        return runtime.evaluateTemplate(expr, prefillInputContext);
+    };
+    var prefillAuth = securities
+        ? resolveTryItPrefillAuthForOperationSecurities({
+            securities: securities,
+            resolveTryItPrefillExpression: resolveTryItPrefillExpression,
+        })
+        : undefined;
+    var prefillServers = servers
+        ? resolveTryItPrefillServersForOperationServers({ servers: servers, resolveTryItPrefillExpression: resolveTryItPrefillExpression })
+        : [];
+    return __assign(__assign({}, (prefillAuth ? { authentication: prefillAuth } : {})), (prefillServers ? { servers: prefillServers } : {}));
+}
+/**
+ * Resolve prefill authentication configuration for the security schemes defined for an operation.
+ */
+function resolveTryItPrefillAuthForOperationSecurities(args) {
+    var _a, _b;
+    var securities = args.securities, resolveTryItPrefillExpression = args.resolveTryItPrefillExpression;
+    var prefillAuthConfig = {};
+    for (var _i = 0, _c = Object.values(securities); _i < _c.length; _i++) {
+        var _d = _c[_i], schemeName = _d[0], security = _d[1];
+        var tryitPrefillAuthValue = security['x-gitbook-prefill']
+            ? resolveTryItPrefillExpression(security['x-gitbook-prefill'])
+            : undefined;
+        if (!tryitPrefillAuthValue) {
+            continue;
+        }
+        switch (security.type) {
+            case 'http': {
+                if ((_a = security.scheme) === null || _a === void 0 ? void 0 : _a.includes('bearer')) {
+                    prefillAuthConfig[schemeName] = { token: tryitPrefillAuthValue };
+                }
+                else if (((_b = security.scheme) === null || _b === void 0 ? void 0 : _b.includes('basic')) &&
+                    tryitPrefillAuthValue.includes(':')) {
+                    var _e = tryitPrefillAuthValue.split(':', 2), username = _e[0], password = _e[1];
+                    prefillAuthConfig[schemeName] = { username: username, password: password };
+                }
+                break;
+            }
+            case 'apiKey': {
+                prefillAuthConfig[schemeName] = {
+                    name: security.name,
+                    in: security.in,
+                    value: tryitPrefillAuthValue,
+                };
+                break;
+            }
+            case 'oauth2':
+            case 'openIdConnect': {
+                break;
+            }
+        }
+    }
+    return Object.keys(prefillAuthConfig).length > 0
+        ? { securitySchemes: prefillAuthConfig }
+        : undefined;
+}
+/**
+ * Resolve prefill server configuration for the servers defined for an operation.
+ */
+function resolveTryItPrefillServersForOperationServers(args) {
+    var servers = args.servers, resolveTryItPrefillExpression = args.resolveTryItPrefillExpression;
+    var resolvedServers = [];
+    for (var _i = 0, servers_1 = servers; _i < servers_1.length; _i++) {
+        var server = servers_1[_i];
+        // Url-level prefill
+        var tryItPrefillServerUrlExpr = server['x-gitbook-prefill'];
+        var tryItPrefillServerUrlValue = tryItPrefillServerUrlExpr
+            ? resolveTryItPrefillExpression(tryItPrefillServerUrlExpr)
+            : undefined;
+        var variables = server.variables
+            ? __assign({}, server.variables) : {};
+        // Variable-level prefill
+        if (server.variables) {
+            for (var _a = 0, _b = Object.entries(server.variables); _a < _b.length; _a++) {
+                var _c = _b[_a], varName = _c[0], variable = _c[1];
+                var tryItPrefillVarExpr = variable["x-gitbook-prefill"], variableProps = __rest(variable, ['x-gitbook-prefill']);
+                var tryItPrefillVarValue = tryItPrefillVarExpr
+                    ? resolveTryItPrefillExpression(tryItPrefillVarExpr)
+                    : undefined;
+                variables[varName] = __assign(__assign({}, variableProps), (tryItPrefillVarValue ? { default: String(tryItPrefillVarValue) } : {}));
+            }
+        }
+        var hasServerVariables = Object.keys(variables).length > 0;
+        if (server.url && (tryItPrefillServerUrlValue || hasServerVariables)) {
+            var resolvedServer = __assign(__assign({ url: tryItPrefillServerUrlValue !== null && tryItPrefillServerUrlValue !== void 0 ? tryItPrefillServerUrlValue : server.url }, (server.description ? { description: server.description } : {})), (hasServerVariables ? { variables: variables } : {}));
+            resolvedServers.push(resolvedServer);
+        }
+    }
+    return resolvedServers.length > 0 ? resolvedServers : undefined;
+}

package/package.json

@@ -8,21 +8,25 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.3.6",
+    "version": "1.4.1",
     "sideEffects": false,
     "dependencies": {
+        "@gitbook/expr": "workspace:*",
         "@gitbook/openapi-parser": "workspace:*",
         "@scalar/api-client-react": "^1.3.16",
         "@scalar/oas-utils": "^0.2.130",
+        "@scalar/types": "^0.1.9",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",
         "react-aria-components": "^1.6.0",
         "react-aria": "^3.37.0",
         "usehooks-ts": "^3.1.0",
-        "zustand": "^5.0.3"
+        "zustand": "^5.0.3",
+        "js-yaml": "^4.1.0"
     },
     "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
         "bun-types": "^1.1.20",
         "typescript": "^5.5.3"
     },

package/src/InteractiveSection.tsx

@@ -112,7 +112,7 @@ export function InteractiveSection(props: {
                             event.stopPropagation();
                         }}
                     >
-                        {tabs.length > 1 ? (
+                        {tabs.length > 0 ? (
                             <OpenAPISelect
                                 stateKey={stateKey}
                                 items={tabs}

package/src/OpenAPICodeSample.tsx

@@ -66,7 +66,11 @@ function generateCodeSamples(props: {
     const searchParams = new URLSearchParams();
     const headersObject: { [k: string]: string } = {};
 
-    data.operation.parameters?.forEach((param) => {
+    // The parser can sometimes returns invalid parameters (an object instead of an array).
+    // It should get fixed in scalar, but in the meantime we just ignore the parameters in that case.
+    const params = Array.isArray(data.operation.parameters) ? data.operation.parameters : [];
+
+    params.forEach((param) => {
         if (!param) {
             return;
         }
@@ -194,7 +198,7 @@ function OpenAPICodeSampleFooter(props: {
     context: OpenAPIContext;
 }) {
     const { data, context, renderers } = props;
-    const { method, path } = data;
+    const { method, path, securities, servers } = data;
     const { specUrl } = context;
     const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
     const hasMultipleMediaTypes =
@@ -226,6 +230,8 @@ function OpenAPICodeSampleFooter(props: {
                     context={getOpenAPIClientContext(context)}
                     method={method}
                     path={path}
+                    securities={securities}
+                    servers={servers}
                     specUrl={specUrl}
                 />
             )}

package/src/OpenAPIPrefillContextProvider.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Prefill data that can be used to dynamically inject info into OpenAPI operation blocks.
+ *
+ * This is typically dynamic input context, such as visitor data or environment info.
+ */
+export type PrefillInputContextData = Record<string, unknown>;
+
+/**
+ * Context value is function that returns prefill data.
+ */
+type PrefillContextValue = () => PrefillInputContextData | null;
+
+const OpenAPIPrefillContext = React.createContext<PrefillContextValue | null>(null);
+
+/**
+ * Provide context to help prefill dynamic info like visitor data in OpenAPI blocks.
+ */
+export function OpenAPIPrefillContextProvider(
+    props: React.PropsWithChildren<{
+        getPrefillInputContextData: () => PrefillInputContextData | null;
+    }>
+) {
+    const { getPrefillInputContextData, children } = props;
+    return (
+        <OpenAPIPrefillContext.Provider value={getPrefillInputContextData}>
+            {children}
+        </OpenAPIPrefillContext.Provider>
+    );
+}
+
+/**
+ * Hook to access the prefill context function.
+ */
+export function useOpenAPIPrefillContext(): PrefillContextValue {
+    return React.useContext(OpenAPIPrefillContext) ?? (() => null);
+}

package/src/OpenAPIResponseExample.tsx

@@ -42,7 +42,13 @@ export function OpenAPIResponseExample(props: {
     });
 
     const tabs = responses
-        .filter(([_, responseObject]) => responseObject && typeof responseObject === 'object')
+        .filter(
+            ([_, responseObject]) =>
+                responseObject &&
+                typeof responseObject === 'object' &&
+                // Make sure the response is not hidden
+                !responseObject['x-hideSample']
+        )
         .map(([key, responseObject]) => {
             const description = resolveDescription(responseObject);
             const label = description ? (

package/src/OpenAPIResponses.tsx

@@ -50,6 +50,20 @@ export function OpenAPIResponses(props: {
                     ];
                 }
 
+                if (!response.content) {
+                    return [
+                        {
+                            key: 'default',
+                            label: '',
+                            body: (
+                                <pre className="openapi-example-empty">
+                                    <p>{t(context.translation, 'no_content')}</p>
+                                </pre>
+                            ),
+                        },
+                    ];
+                }
+
                 return Object.entries(response.content ?? {}).map(([contentType, mediaType]) => ({
                     key: contentType,
                     label: contentType,

package/src/OpenAPISpec.tsx

@@ -117,19 +117,22 @@ function getParameterGroupName(paramIn: string, context: OpenAPIClientContext):
 /** Deduplicate parameters by name and in.
  * Some specs have both parameters define at path and operation level.
  * We only want to display one of them.
+ * Parameters can have the wrong type (object instead of array) sometimes, we just return an empty array in that case.
  */
 function deduplicateParameters(parameters: OpenAPI.Parameters): OpenAPI.Parameters {
     const seen = new Set();
 
-    return parameters.filter((param) => {
-        const key = `${param.name}:${param.in}`;
+    return Array.isArray(parameters)
+        ? parameters.filter((param) => {
+              const key = `${param.name}:${param.in}`;
 
-        if (seen.has(key)) {
-            return false;
-        }
+              if (seen.has(key)) {
+                  return false;
+              }
 
-        seen.add(key);
+              seen.add(key);
 
-        return true;
-    });
+              return true;
+          })
+        : [];
 }

package/src/ScalarApiButton.tsx

@@ -1,13 +1,16 @@
 'use client';
 
 import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-react';
-import { useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { Suspense, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
 import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
+import { useOpenAPIPrefillContext } from './OpenAPIPrefillContextProvider';
 import type { OpenAPIClientContext } from './context';
 import { t } from './translate';
+import type { OpenAPIOperationData } from './types';
+import { resolveTryItPrefillForOperation } from './util/tryit-prefill';
 
 /**
  * Button which launches the Scalar API Client
@@ -15,12 +18,15 @@ import { t } from './translate';
 export function ScalarApiButton(props: {
     method: OpenAPIV3_1.HttpMethods;
     path: string;
+    securities: OpenAPIOperationData['securities'];
+    servers: OpenAPIOperationData['servers'];
     specUrl: string;
     context: OpenAPIClientContext;
 }) {
-    const { method, path, specUrl, context } = props;
+    const { method, path, securities, servers, specUrl, context } = props;
     const [isOpen, setIsOpen] = useState(false);
     const controllerRef = useRef<ScalarModalControllerRef>(null);
+
     return (
         <div className="scalar scalar-activate">
             <button
@@ -42,12 +48,16 @@ export function ScalarApiButton(props: {
 
             {isOpen &&
                 createPortal(
-                    <ScalarModal
-                        controllerRef={controllerRef}
-                        method={method}
-                        path={path}
-                        specUrl={specUrl}
-                    />,
+                    <Suspense fallback={null}>
+                        <ScalarModal
+                            controllerRef={controllerRef}
+                            method={method}
+                            path={path}
+                            securities={securities}
+                            servers={servers}
+                            specUrl={specUrl}
+                        />
+                    </Suspense>,
                     document.body
                 )}
         </div>
@@ -57,12 +67,26 @@ export function ScalarApiButton(props: {
 function ScalarModal(props: {
     method: OpenAPIV3_1.HttpMethods;
     path: string;
+    securities: OpenAPIOperationData['securities'];
+    servers: OpenAPIOperationData['servers'];
     specUrl: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
-    const { method, path, specUrl, controllerRef } = props;
+    const { method, path, securities, servers, specUrl, controllerRef } = props;
+
+    const getPrefillInputContextData = useOpenAPIPrefillContext();
+    const prefillInputContext = getPrefillInputContextData();
+
+    const prefillConfig = resolveTryItPrefillForOperation({
+        operation: { securities, servers },
+        prefillInputContext,
+    });
+
     return (
-        <ApiClientModalProvider configuration={{ url: specUrl }} initialRequest={{ method, path }}>
+        <ApiClientModalProvider
+            configuration={{ url: specUrl, ...prefillConfig }}
+            initialRequest={{ method, path }}
+        >
             <ScalarModalController method={method} path={path} controllerRef={controllerRef} />
         </ApiClientModalProvider>
     );
@@ -84,7 +108,11 @@ function ScalarModalController(props: {
     const openClient = useMemo(() => {
         if (openScalarClient) {
             return () => {
-                openScalarClient({ method, path, _source: 'gitbook' });
+                openScalarClient({
+                    method,
+                    path,
+                    _source: 'gitbook',
+                });
                 trackClientOpening({ method, path });
             };
         }

package/src/code-samples.test.ts

@@ -406,7 +406,7 @@ describe('python code sample generator', () => {
 
     it('should format application/json body properly', () => {
         const input: CodeSampleInput = {
-            method: 'GET',
+            method: 'POST',
             url: 'https://example.com/path',
             headers: {
                 'Content-Type': 'application/json',
@@ -422,7 +422,7 @@ describe('python code sample generator', () => {
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({\n      "key": "value",\n      "truethy": True,\n      "falsey": False,\n      "nullish": None\n    })\n)\n\ndata = response.json()'
+            'import json\nimport requests\n\nresponse = requests.post(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({\n      "key": "value",\n      "truethy": True,\n      "falsey": False,\n      "nullish": None\n    })\n)\n\ndata = response.json()'
         );
     });
 

package/src/code-samples.ts

@@ -1,3 +1,4 @@
+import yaml from 'js-yaml';
 import {
     isCSV,
     isFormData,
@@ -8,6 +9,7 @@ import {
     isPlainObject,
     isText,
     isXML,
+    isYAML,
 } from './contentTypeChecks';
 import { json2xml } from './json2xml';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
@@ -154,7 +156,8 @@ ${headerString}${bodyString}`;
         label: 'Python',
         syntax: 'python',
         generate: ({ method, url, headers, body }) => {
-            let code = 'import requests\n\n';
+            const contentType = headers?.['Content-Type'];
+            let code = `${isJSON(contentType) ? 'import json\n' : ''}import requests\n\n`;
 
             if (body) {
                 const lines = BodyGenerators.getPythonBody(body, headers);
@@ -174,7 +177,6 @@ ${headerString}${bodyString}`;
                 code += indent(`headers=${stringifyOpenAPI(headers)},\n`, 4);
             }
 
-            const contentType = headers?.['Content-Type'];
             if (body) {
                 if (body === 'files') {
                     code += indent(`files=${body}\n`, 4);
@@ -256,6 +258,8 @@ const BodyGenerators = {
         } else if (isPDF(contentType)) {
             // We use --data-binary to avoid cURL converting newlines to \r\n
             body = `--data-binary '@${String(body)}'`;
+        } else if (isYAML(contentType)) {
+            body = `--data-binary $'${yaml.dump(body).replace(/'/g, '').replace(/\\n/g, '\n')}'`;
         } else {
             body = `--data '${stringifyOpenAPI(body, null, 2).replace(/\\n/g, '\n')}'`;
         }
@@ -325,6 +329,9 @@ const BodyGenerators = {
             code += indent(convertBodyToXML(body), 4);
             code += '`;\n\n';
             body = 'xml';
+        } else if (isYAML(contentType)) {
+            code += `const yamlBody = \`\n${indent(yaml.dump(body), 4)}\`;\n\n`;
+            body = 'yamlBody';
         } else if (isText(contentType)) {
             body = stringifyOpenAPI(body, null, 2);
         } else {
@@ -355,6 +362,9 @@ const BodyGenerators = {
         } else if (isXML(contentType)) {
             // Convert JSON to XML if needed
             body = JSON.stringify(convertBodyToXML(body));
+        } else if (isYAML(contentType)) {
+            code += `yamlBody = \"\"\"\n${indent(yaml.dump(body), 4)}\"\"\"\n\n`;
+            body = 'yamlBody';
         } else {
             body = stringifyOpenAPI(
                 body,
@@ -399,6 +409,7 @@ const BodyGenerators = {
                 // Convert JSON to XML if needed
                 return `"${convertBodyToXML(body)}"`;
             },
+            yaml: () => `"${yaml.dump(body).replace(/"/g, '\\"')}"`,
             csv: () => `"${stringifyOpenAPI(body).replace(/"/g, '')}"`,
             default: () => `${stringifyOpenAPI(body, null, 2)}`,
         };
@@ -407,6 +418,7 @@ const BodyGenerators = {
         if (isFormUrlEncoded(contentType)) return typeHandlers.formUrlEncoded();
         if (isText(contentType)) return typeHandlers.text();
         if (isXML(contentType)) return typeHandlers.xml();
+        if (isYAML(contentType)) return typeHandlers.yaml();
         if (isCSV(contentType)) return typeHandlers.csv();
 
         return typeHandlers.default();

package/src/contentTypeChecks.ts

@@ -6,6 +6,10 @@ export function isXML(contentType?: string): boolean {
     return contentType?.toLowerCase().includes('application/xml') || false;
 }
 
+export function isYAML(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/yaml') || false;
+}
+
 export function isGraphQL(contentType?: string): boolean {
     return contentType?.toLowerCase().includes('application/graphql') || false;
 }

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './schemas';
 export * from './OpenAPIOperation';
 export * from './OpenAPIWebhook';
 export * from './OpenAPIOperationContext';
+export * from './OpenAPIPrefillContextProvider';
 export * from './resolveOpenAPIOperation';
 export * from './resolveOpenAPIWebhook';
 export type { OpenAPIOperationData, OpenAPIWebhookData } from './types';

package/src/types.ts

@@ -1,17 +1,31 @@
 import type {
     OpenAPICustomOperationProperties,
+    OpenAPICustomPrefillProperties,
     OpenAPICustomSpecProperties,
     OpenAPIV3,
 } from '@gitbook/openapi-parser';
 
-export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & { required?: boolean };
+export type OpenAPIServerVariableWithCustomProperties = OpenAPIV3.ServerVariableObject &
+    OpenAPICustomPrefillProperties;
+
+/**
+ * OpenAPI ServerObject type extended to provide x-gitbook prefill custom properties at the variable level.
+ */
+export type OpenAPIServerWithCustomProperties = Omit<OpenAPIV3.ServerObject, 'variables'> & {
+    variables?: {
+        [variable: string]: OpenAPIServerVariableWithCustomProperties;
+    };
+} & OpenAPICustomPrefillProperties;
+
+export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject &
+    OpenAPICustomPrefillProperties & { required?: boolean };
 
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     path: string;
     method: string;
 
     /** Servers to be used for this operation */
-    servers: OpenAPIV3.ServerObject[];
+    servers: OpenAPIServerWithCustomProperties[];
 
     /** Spec of the operation */
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;