fumadocs-openapi 4.4.1 → 5.0.0

package/dist/server/index.d.ts

@@ -0,0 +1,211 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { ComponentType, ReactNode, FC } from 'react';
+import Slugger from 'github-slugger';
+import { BuildPageTreeOptions } from 'fumadocs-core/source';
+
+interface BaseRequestField {
+    name: string;
+    description?: string;
+}
+interface BaseSchema {
+    description?: string;
+    isRequired: boolean;
+}
+type PrimitiveRequestField = BaseRequestField & PrimitiveSchema;
+interface PrimitiveSchema extends BaseSchema {
+    type: 'boolean' | 'string' | 'number';
+    defaultValue: string;
+}
+interface ReferenceSchema extends BaseSchema {
+    type: 'ref';
+    schema: string;
+}
+interface ArraySchema extends BaseSchema {
+    type: 'array';
+    /**
+     * Reference to item schema or the schema
+     */
+    items: string | RequestSchema;
+}
+interface FileSchema extends BaseSchema {
+    type: 'file';
+}
+interface ObjectSchema extends BaseSchema {
+    type: 'object';
+    properties: Record<string, ReferenceSchema>;
+    /**
+     * Reference to schema, or true if it's `any`
+     */
+    additionalProperties?: boolean | string;
+}
+interface SwitcherSchema extends BaseSchema {
+    type: 'switcher';
+    items: Record<string, ReferenceSchema | RequestSchema>;
+}
+interface NullSchema extends BaseSchema {
+    type: 'null';
+}
+type RequestSchema = PrimitiveSchema | ArraySchema | ObjectSchema | SwitcherSchema | NullSchema | FileSchema;
+interface APIPlaygroundProps {
+    route: string;
+    method: string;
+    bodyType: 'json' | 'form-data';
+    authorization?: PrimitiveRequestField;
+    path?: PrimitiveRequestField[];
+    query?: PrimitiveRequestField[];
+    header?: PrimitiveRequestField[];
+    body?: RequestSchema;
+    schemas: Record<string, RequestSchema>;
+}
+
+interface ResponsesProps {
+    items: string[];
+    children: ReactNode;
+}
+interface ResponseProps {
+    value: string;
+    children: ReactNode;
+}
+interface APIInfoProps {
+    method: string;
+    route: string;
+    children: ReactNode;
+}
+interface PropertyProps {
+    name: string;
+    type: string;
+    required?: boolean;
+    deprecated?: boolean;
+    children?: ReactNode;
+}
+interface ObjectCollapsibleProps {
+    name: string;
+    children: ReactNode;
+}
+interface RequestProps {
+    language: string;
+    name: string;
+    code: string;
+}
+interface ResponseTypeProps {
+    lang: string;
+    code: string;
+    label: string;
+}
+interface RootProps {
+    baseUrl?: string;
+    children: ReactNode;
+}
+interface Renderer {
+    Root: ComponentType<RootProps>;
+    API: ComponentType<{
+        children: ReactNode;
+    }>;
+    APIInfo: ComponentType<APIInfoProps>;
+    APIExample: ComponentType<{
+        children: ReactNode;
+    }>;
+    Responses: ComponentType<ResponsesProps>;
+    Response: ComponentType<ResponseProps>;
+    Requests: ComponentType<{
+        items: string[];
+        children: ReactNode;
+    }>;
+    Request: ComponentType<RequestProps>;
+    ResponseTypes: ComponentType<{
+        children: ReactNode;
+    }>;
+    ResponseType: ComponentType<ResponseTypeProps>;
+    /**
+     * Collapsible to show object schemas
+     */
+    ObjectCollapsible: ComponentType<ObjectCollapsibleProps>;
+    Property: ComponentType<PropertyProps>;
+    APIPlayground: ComponentType<APIPlaygroundProps>;
+}
+
+/**
+ * Sample info of endpoint
+ */
+interface EndpointSample {
+    /**
+     * Request URL, including path and query parameters
+     */
+    url: string;
+    method: string;
+    body?: {
+        schema: OpenAPIV3.SchemaObject;
+        mediaType: string;
+        sample: unknown;
+    };
+    responses: Record<string, ResponseSample>;
+    parameters: ParameterSample[];
+}
+interface ResponseSample {
+    mediaType: string;
+    sample: unknown;
+    schema: OpenAPIV3.SchemaObject;
+}
+interface ParameterSample {
+    name: string;
+    in: string;
+    schema: OpenAPIV3.SchemaObject;
+    sample: unknown;
+}
+
+interface CodeSample {
+    lang: string;
+    label: string;
+    source: string;
+}
+
+type Awaitable<T> = T | Promise<T>;
+interface RenderContext {
+    renderer: Renderer;
+    document: OpenAPIV3.Document;
+    baseUrl: string;
+    slugger: Slugger;
+    /**
+     * Generate TypeScript definitions from response schema.
+     *
+     * Pass `false` to disable it.
+     *
+     * @param endpoint - the API endpoint
+     * @param code - status code
+     */
+    generateTypeScriptSchema?: ((endpoint: EndpointSample, code: string) => Awaitable<string>) | false;
+    /**
+     * Generate code samples for endpoint.
+     */
+    generateCodeSamples?: (endpoint: EndpointSample) => Awaitable<CodeSample[]>;
+}
+
+interface ApiPageProps {
+    /**
+     * An array of operation
+     */
+    operations: {
+        path: string;
+        method: OpenAPIV3.HttpMethods;
+    }[];
+    hasHead: boolean;
+    ctx: RenderContext;
+}
+
+interface OpenAPIOptions extends Pick<RenderContext, 'generateCodeSamples' | 'generateTypeScriptSchema'> {
+    documentOrPath: string | OpenAPIV3.Document;
+    renderer?: Partial<Renderer>;
+}
+interface OpenAPIServer {
+    APIPage: FC<Omit<ApiPageProps, 'ctx'>>;
+}
+declare function createOpenAPI(options: OpenAPIOptions): OpenAPIServer;
+
+/**
+ * Source API Integration
+ *
+ * Add this to page tree builder options
+ */
+declare const attachFile: BuildPageTreeOptions['attachFile'];
+
+export { type OpenAPIOptions, type OpenAPIServer, attachFile, createOpenAPI };