@gitbook/react-openapi 1.1.10 → 1.2.0

package/src/translations/zh.ts

@@ -0,0 +1,37 @@
+export const zh = {
+    required: '必填',
+    deprecated: '已弃用',
+    deprecated_and_sunset_on: '此操作已弃用，将于 ${1} 停止使用。',
+    stability_experimental: '实验性',
+    stability_alpha: 'Alpha',
+    stability_beta: 'Beta',
+    copy_to_clipboard: '复制到剪贴板',
+    copied: '已复制',
+    no_content: '无内容',
+    unresolved_reference: '未解析的引用',
+    circular_reference: '循环引用',
+    read_only: '只读',
+    write_only: '只写',
+    optional: '可选',
+    min: '最小值',
+    max: '最大值',
+    nullable: '可为 null',
+    body: '请求体',
+    payload: '有效载荷',
+    headers: '头部信息',
+    authorizations: '授权',
+    responses: '响应',
+    path_parameters: '路径参数',
+    query_parameters: '查询参数',
+    header_parameters: '头参数',
+    attributes: '属性',
+    test_it: '测试一下',
+    information: '信息',
+    success: '成功',
+    redirect: '重定向',
+    error: '错误',
+    show: '显示',
+    hide: '隐藏',
+    available_items: '可用项',
+    child_attributes: '子属性',
+};

package/src/types.ts

@@ -4,59 +4,6 @@ import type {
     OpenAPIV3,
 } from '@gitbook/openapi-parser';
 
-export interface OpenAPIClientContext {
-    /**
-     * Icons used in the block.
-     */
-    icons: {
-        chevronDown: React.ReactNode;
-        chevronRight: React.ReactNode;
-        plus: React.ReactNode;
-    };
-
-    /**
-     * Force all sections to be opened by default.
-     * @default false
-     */
-    defaultInteractiveOpened?: boolean;
-
-    /**
-     * The key of the block
-     */
-    blockKey?: string;
-
-    /**
-     * Optional id attached to the heading and used as an anchor.
-     */
-    id?: string;
-}
-
-export interface OpenAPIContext extends OpenAPIClientContext {
-    /**
-     * Render a code block.
-     */
-    renderCodeBlock: (props: { code: string; syntax: string }) => React.ReactNode;
-
-    /**
-     * Render the heading of the operation.
-     */
-    renderHeading: (props: {
-        deprecated?: boolean;
-        title: string;
-        stability?: string;
-    }) => React.ReactNode;
-
-    /**
-     * Render the document of the operation.
-     */
-    renderDocument: (props: { document: object }) => React.ReactNode;
-
-    /**
-     * Specification URL.
-     */
-    specUrl: string;
-}
-
 export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & { required?: boolean };
 
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
@@ -72,3 +19,14 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Securities that should be used for this operation */
     securities: [string, OpenAPISecurityWithRequired][];
 }
+
+export interface OpenAPIWebhookData extends OpenAPICustomSpecProperties {
+    name: string;
+    method: string;
+
+    /** Servers to be used for this operation */
+    servers: OpenAPIV3.ServerObject[];
+
+    /** Spec of the webhook */
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+}

package/src/util/example.tsx

@@ -0,0 +1,129 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPIExample } from '../OpenAPIExample';
+import type { OpenAPIContext } from '../context';
+import { generateSchemaExample } from '../generateSchemaExample';
+import { tString } from '../translate';
+import { checkIsReference } from '../utils';
+
+/**
+ * Generate an example from a reference object.
+ */
+export function getExampleFromReference(
+    ref: OpenAPIV3.ReferenceObject,
+    context: OpenAPIContext
+): OpenAPIV3.ExampleObject {
+    return {
+        summary: tString(context.translation, 'unresolved_reference'),
+        value: { $ref: ref.$ref },
+    };
+}
+
+/**
+ * Get examples from a media type object.
+ */
+export function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    context: OpenAPIContext;
+}): { key: string; example: OpenAPIV3.ExampleObject }[] {
+    const { mediaTypeObject, mediaType, context } = args;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+            return {
+                key,
+                example: checkIsReference(example)
+                    ? getExampleFromReference(example, context)
+                    : example,
+            };
+        });
+    }
+
+    if (mediaTypeObject.example) {
+        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
+    }
+
+    if (mediaTypeObject.schema) {
+        if (mediaType === 'application/xml') {
+            // @TODO normally we should use the name of the schema but we don't have it
+            // fix it when we got the reference name
+            const root = mediaTypeObject.schema.xml?.name ?? 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: {
+                            [root]: generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                                mode: 'read',
+                            }),
+                        },
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: {
+                    value: generateSchemaExample(mediaTypeObject.schema, {
+                        mode: 'read',
+                    }),
+                },
+            },
+        ];
+    }
+    return [];
+}
+
+/**
+ * Get example from a schema object.
+ */
+export function getExampleFromSchema(args: {
+    schema: OpenAPIV3.SchemaObject;
+}): OpenAPIV3.ExampleObject {
+    const { schema } = args;
+
+    if (schema.example) {
+        return { value: schema.example };
+    }
+
+    return { value: generateSchemaExample(schema, { mode: 'read' }) };
+}
+
+/**
+ * Get the examples from a media type object.
+ */
+export function getExamples(props: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContext;
+}) {
+    const { mediaTypeObject, mediaType, context } = props;
+    const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType, context });
+    const syntax = getSyntaxFromMediaType(mediaType);
+
+    return examples.map((example) => {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (
+                <OpenAPIExample example={example.example} context={props.context} syntax={syntax} />
+            ),
+        };
+    });
+}
+
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType: string): string {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+
+    return 'text';
+}

package/src/utils.ts

@@ -1,5 +1,7 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import type { OpenAPIUniversalContext } from './context';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { tString } from './translate';
 
 export function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject {
     return typeof input === 'object' && !!input && '$ref' in input;
@@ -149,3 +151,68 @@ function shouldDisplayExample(schema: OpenAPIV3.SchemaObject): boolean {
             Object.keys(schema.example).length > 0)
     );
 }
+
+/**
+ * Get the class name for a status code.
+ * 1xx: informational
+ * 2xx: success
+ * 3xx: redirect
+ * 4xx, 5xx: error
+ */
+export function getStatusCodeClassName(statusCode: number | string): string {
+    const category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return 'informational';
+        case 2:
+            return 'success';
+        case 3:
+            return 'redirect';
+        case 4:
+        case 5:
+            return 'error';
+        default:
+            return 'unknown';
+    }
+}
+
+/**
+ * Get a default label for a status code.
+ * This is used when there is no label provided in the OpenAPI spec.
+ * 1xx: Information
+ * 2xx: Success
+ * 3xx: Redirect
+ * 4xx, 5xx: Error
+ */
+export function getStatusCodeDefaultLabel(
+    statusCode: number | string,
+    context: OpenAPIUniversalContext
+): string {
+    const category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return tString(context.translation, 'information');
+        case 2:
+            return tString(context.translation, 'success');
+        case 3:
+            return tString(context.translation, 'redirect');
+        case 4:
+        case 5:
+            return tString(context.translation, 'error');
+        default:
+            return '';
+    }
+}
+
+function getStatusCodeCategory(statusCode: number | string): number | string {
+    const code = typeof statusCode === 'string' ? Number.parseInt(statusCode, 10) : statusCode;
+
+    if (Number.isNaN(code) || code < 100 || code >= 600) {
+        return 'unknown';
+    }
+
+    // Determine the category of the status code based on the first digit
+    const category = Math.floor(code / 100);
+
+    return category;
+}