apiskill 0.1.0

package/src/swagger.ts

@@ -0,0 +1,664 @@
+import type {
+  Endpoint,
+  FieldRow,
+  HttpMethod,
+  SwaggerDocument,
+  SwaggerOperation,
+  SwaggerParameter,
+  SwaggerSchema,
+} from './types';
+import { formatManualApiCliConfig } from './manualApiConfig';
+import type { ManualApiFieldConfig, ManualApiOperationConfig, ManualApiResponseConfig } from './manualApiConfig';
+
+export const IMPORT_API_URL = '/api/openapi/import';
+export const DOCUMENT_CREATE_API_URL = '/api/openapi/document';
+export const AUTH_CHECK_API_URL = '/api/openapi/auth-check';
+export const CACHE_API_URL = '/api/openapi/cache';
+export const VERSIONS_API_URL = '/api/openapi/versions';
+export const VERSION_SELECT_API_URL = '/api/openapi/version-select';
+export const VERSION_META_API_URL = '/api/openapi/version-meta';
+export const VERSION_DELETE_API_URL = '/api/openapi/version-delete';
+export const VERSION_EXPORT_API_URL = '/api/openapi/version-export';
+export const MOCK_START_API_URL = '/api/mock/start';
+export const MOCK_STATUS_API_URL = '/api/mock/status';
+export const MOCK_STOP_API_URL = '/api/mock/stop';
+export const CUSTOM_OPERATION_API_URL = '/api/openapi/custom-operation';
+export const DELETE_OPERATION_API_URL = '/api/openapi/custom-operation/delete';
+export const OPERATION_LINKS_API_URL = '/api/openapi/operation-links';
+export const STORAGE_SYNC_KEY = 'apiskill.swagger.syncedAt.v1';
+export const STORAGE_SOURCE_KEY = 'apiskill.swagger.sourceUrl.v1';
+
+const HTTP_METHODS: HttpMethod[] = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head'];
+const MAX_DEPTH = 12;
+
+export function listEndpoints(doc: SwaggerDocument): Endpoint[] {
+  const paths = doc.paths ?? {};
+
+  return Object.entries(paths)
+    .flatMap(([path, pathItem]) =>
+      HTTP_METHODS.flatMap((method) => {
+        const operation = pathItem?.[method];
+        if (!operation) return [];
+
+        const tags = operation.tags?.length ? operation.tags : ['未分组'];
+        const summary = operation.summary || operation.description || '未命名接口';
+        const params = operation.parameters ?? [];
+        const searchable = [
+          method,
+          path,
+          summary,
+          operation.description,
+          operation.operationId,
+          tags.join(' '),
+          params.map((item) => `${item.name} ${item.description ?? ''}`).join(' '),
+        ]
+          .filter(Boolean)
+          .join(' ')
+          .toLowerCase();
+
+        return [
+          {
+            id: `${method.toUpperCase()} ${path}`,
+            path,
+            method,
+            operation,
+            tags,
+            summary,
+            hasBody: operationHasBody(operation),
+            searchable,
+          },
+        ];
+      }),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+
+export function listTags(endpoints: Endpoint[]) {
+  const tagMap = new Map<string, number>();
+  endpoints.forEach((endpoint) => {
+    endpoint.tags.forEach((tag) => tagMap.set(tag, (tagMap.get(tag) ?? 0) + 1));
+  });
+
+  return [...tagMap.entries()]
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+
+export function getSchemaName(ref?: string) {
+  if (!ref) return '';
+  return decodeURIComponent(ref.split('/').pop() ?? ref);
+}
+
+export function resolveSchema(doc: SwaggerDocument, schema?: SwaggerSchema, seen = new Set<string>()): SwaggerSchema | undefined {
+  if (!schema) return undefined;
+
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) {
+      return {
+        type: 'object',
+        description: `循环引用: ${getSchemaName(schema.$ref)}`,
+      };
+    }
+    seen.add(schema.$ref);
+    const resolved = schema.$ref.startsWith('#/')
+      ? schema.$ref
+          .slice(2)
+          .split('/')
+          .reduce<unknown>((current, key) => {
+            if (current && typeof current === 'object') {
+              return (current as Record<string, unknown>)[decodeURIComponent(key)];
+            }
+            return undefined;
+          }, doc)
+      : undefined;
+    return resolveSchema(doc, resolved as SwaggerSchema | undefined, seen);
+  }
+
+  if (schema.allOf?.length) {
+    return mergeSchemas(doc, schema.allOf, schema);
+  }
+
+  return schema;
+}
+
+function mergeSchemas(doc: SwaggerDocument, schemas: SwaggerSchema[], base: SwaggerSchema): SwaggerSchema {
+  return schemas.reduce<SwaggerSchema>(
+    (merged, item) => {
+      const resolved = resolveSchema(doc, item) ?? {};
+      return {
+        ...merged,
+        ...resolved,
+        description: [merged.description, resolved.description].filter(Boolean).join('；') || merged.description,
+        required: [...new Set([...(merged.required ?? []), ...(resolved.required ?? [])])],
+        properties: {
+          ...(merged.properties ?? {}),
+          ...(resolved.properties ?? {}),
+        },
+      };
+    },
+    { ...base, allOf: undefined },
+  );
+}
+
+export function schemaType(doc: SwaggerDocument, schema?: SwaggerSchema): string {
+  if (!schema) return '-';
+  if (schema.$ref) return getSchemaName(schema.$ref);
+
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  if (resolved.enum?.length) {
+    const enumText = resolved.enum.map(formatValue).join(' | ');
+    return `${resolved.type ?? 'enum'}<${enumText}>`;
+  }
+  if (resolved.type === 'array') return `${schemaType(doc, resolved.items)}[]`;
+  if (resolved.anyOf?.length) return resolved.anyOf.map((item) => schemaType(doc, item)).join(' | ');
+  if (resolved.oneOf?.length) return resolved.oneOf.map((item) => schemaType(doc, item)).join(' | ');
+  if (resolved.additionalProperties && typeof resolved.additionalProperties === 'object') {
+    return `Record<string, ${schemaType(doc, resolved.additionalProperties)}>`;
+  }
+
+  return [resolved.type, resolved.format].filter(Boolean).join(':') || 'object';
+}
+
+export function schemaDescription(schema?: SwaggerSchema) {
+  return schema?.description?.trim() || '';
+}
+
+export function flattenSchema(
+  doc: SwaggerDocument,
+  schema?: SwaggerSchema,
+  options: {
+    prefix?: string;
+    requiredFields?: string[];
+    depth?: number;
+    seen?: Set<string>;
+    location?: string;
+  } = {},
+): FieldRow[] {
+  const depth = options.depth ?? 0;
+  if (!schema || depth > MAX_DEPTH) return [];
+
+  if (schema.$ref) {
+    if (options.seen?.has(schema.$ref)) {
+      return [
+        {
+          name: options.prefix || getSchemaName(schema.$ref),
+          path: options.prefix || getSchemaName(schema.$ref),
+          location: options.location,
+          required: false,
+          type: getSchemaName(schema.$ref),
+          description: '循环引用，已停止展开',
+          defaultValue: '',
+          enumValue: '',
+          depth,
+        },
+      ];
+    }
+    const nextSeen = new Set(options.seen ?? []);
+    nextSeen.add(schema.$ref);
+    return flattenSchema(doc, resolveSchema(doc, schema), { ...options, seen: nextSeen });
+  }
+
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  const rows: FieldRow[] = [];
+  const properties = resolved.properties ?? {};
+  const requiredFields = resolved.required ?? options.requiredFields ?? [];
+
+  if (resolved.type === 'array') {
+    const name = options.prefix || '[]';
+    rows.push(toRow(doc, name, name, resolved, false, depth, options.location));
+    rows.push(
+      ...flattenSchema(doc, resolved.items, {
+        ...options,
+        prefix: `${name}[]`,
+        depth: depth + 1,
+      }),
+    );
+    return rows;
+  }
+
+  if (Object.keys(properties).length === 0) {
+    if (options.prefix) {
+      rows.push(toRow(doc, options.prefix.split('.').pop() ?? options.prefix, options.prefix, resolved, false, depth, options.location));
+    }
+    return rows;
+  }
+
+  sortedEntries(properties).forEach(([name, property]) => {
+    const path = options.prefix ? `${options.prefix}.${name}` : name;
+    const propertyRequired = requiredFields.includes(name);
+    rows.push(toRow(doc, name, path, property, propertyRequired, depth, options.location));
+
+    const child = resolveSchema(doc, property) ?? property;
+    const childHasNested =
+      child.type === 'array' || Boolean(child.properties && Object.keys(child.properties).length) || Boolean(child.$ref);
+    if (childHasNested) {
+      if (child.type === 'array') {
+        const item = child.items;
+        const itemResolved = resolveSchema(doc, item) ?? item;
+        rows.push(
+          ...flattenSchema(doc, item, {
+            ...options,
+            prefix: `${path}[]`,
+            requiredFields: itemResolved?.required,
+            depth: depth + 1,
+          }),
+        );
+        return;
+      }
+
+      rows.push(
+        ...flattenSchema(doc, property, {
+          ...options,
+          prefix: path,
+          requiredFields: child.required,
+          depth: depth + 1,
+        }),
+      );
+    }
+  });
+
+  return rows;
+}
+
+export function parameterRows(doc: SwaggerDocument, parameters: SwaggerParameter[] = []): FieldRow[] {
+  return sortFieldRows(parameters
+    .filter((parameter) => parameter.in !== 'body')
+    .map((parameter) => {
+      const schema = parameterSchema(parameter);
+      return {
+        name: parameter.name,
+        path: parameter.name,
+        location: parameter.in,
+        required: Boolean(parameter.required),
+        type: schemaType(doc, schema),
+        description: parameter.description || schemaDescription(schema) || '',
+        defaultValue: schema?.default === undefined ? '' : formatValue(schema.default),
+        enumValue: schema?.enum?.map(formatValue).join(', ') ?? '',
+        depth: 0,
+      };
+    }));
+}
+
+export function requestBodyRows(doc: SwaggerDocument, operation: SwaggerOperation): Record<string, FieldRow[]> {
+  const content = operation.requestBody?.content ?? {};
+  const openApiRows = Object.fromEntries(
+    Object.entries(content).map(([mediaType, media]) => [
+      mediaType,
+      sortFieldRows(flattenSchema(doc, media.schema).map((row) => ({
+        ...row,
+        location: 'body',
+      }))),
+    ]),
+  );
+  if (Object.keys(openApiRows).length) return openApiRows;
+
+  const bodyParameter = operation.parameters?.find((parameter) => parameter.in === 'body');
+  if (!bodyParameter?.schema) return {};
+  const mediaTypes = operation.consumes?.length ? operation.consumes : ['application/json'];
+  return Object.fromEntries(
+    mediaTypes.map((mediaType) => [
+      mediaType,
+      sortFieldRows(flattenSchema(doc, bodyParameter.schema).map((row) => ({
+        ...row,
+        location: 'body',
+      }))),
+    ]),
+  );
+}
+
+export function responseRows(doc: SwaggerDocument, operation: SwaggerOperation): Record<string, Record<string, FieldRow[]>> {
+  const responses = operation.responses ?? {};
+  return Object.fromEntries(
+    Object.entries(responses).map(([status, response]) => {
+      const content = response.content ?? {};
+      const openApiRows = Object.fromEntries(
+        Object.entries(content).map(([mediaType, media]) => [
+          mediaType,
+          sortFieldRows(flattenSchema(doc, media.schema).map((row) => ({
+            ...row,
+            location: `response ${status}`,
+          }))),
+        ]),
+      );
+      if (Object.keys(openApiRows).length) return [status, openApiRows];
+
+      const schema = response.schema ?? response.responseSchema;
+      if (!schema) return [status, {}];
+      const mediaTypes = operation.produces?.length ? operation.produces : ['application/json'];
+      return [
+        status,
+        Object.fromEntries(
+          mediaTypes.map((mediaType) => [
+            mediaType,
+            sortFieldRows(flattenSchema(doc, schema).map((row) => ({
+              ...row,
+              location: `response ${status}`,
+            }))),
+          ]),
+        ),
+      ];
+    }),
+  );
+}
+
+export function buildAiMarkdown(doc: SwaggerDocument, endpoint: Endpoint) {
+  const op = endpoint.operation;
+  const parameterText = rowsToMarkdown(parameterRows(doc, op.parameters), '无参数');
+  const requestBodies = requestBodyRows(doc, op);
+  const responses = responseRows(doc, op);
+
+  const requestText = Object.keys(requestBodies).length
+    ? Object.entries(requestBodies)
+        .map(([mediaType, rows]) => `### Request Body: ${mediaType}\n${rowsToMarkdown(rows, '空对象或无字段说明')}`)
+        .join('\n\n')
+    : '### Request Body\n无请求体';
+
+  const responseText = Object.entries(op.responses ?? {})
+    .map(([status, response]) => {
+      const medias = responses[status] ?? {};
+      const rows = Object.entries(medias);
+      if (!rows.length) {
+        return `### Response ${status}\n- Description: ${response.description || '无'}\n- Fields: 无字段说明`;
+      }
+      return rows
+        .map(
+          ([mediaType, fields]) =>
+            `### Response ${status}: ${mediaType}\n- Description: ${response.description || '无'}\n${rowsToMarkdown(fields, '空对象或无字段说明')}`,
+        )
+        .join('\n\n');
+    })
+    .join('\n\n');
+
+  return [
+    `# API: ${endpoint.method.toUpperCase()} ${endpoint.path}`,
+    `- Summary: ${endpoint.summary}`,
+    `- Tags: ${endpoint.tags.join(', ')}`,
+    op.operationId ? `- OperationId: ${op.operationId}` : '',
+    op.description ? `- Description: ${op.description}` : '',
+    '',
+    '## Request Parameters',
+    parameterText,
+    '',
+    requestText,
+    '',
+    '## Responses',
+    responseText || '无响应说明',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+export function endpointToManualApiOperationConfig(doc: SwaggerDocument, endpoint: Endpoint): ManualApiOperationConfig {
+  const op = endpoint.operation;
+  const firstRequestBody = firstRequestBodySchema(op);
+
+  return {
+    method: endpoint.method,
+    path: endpoint.path,
+    summary: endpoint.summary,
+    description: op.description || '',
+    operationId: op.operationId || '',
+    tags: endpoint.tags,
+    parameters: parameterRows(doc, op.parameters).map(rowToManualField),
+    requestBody: {
+      required: firstRequestBody?.required ?? false,
+      contentType: firstRequestBody?.contentType || 'application/json',
+      fields: firstRequestBody?.schema ? schemaToManualFields(doc, firstRequestBody.schema) : [],
+    },
+    responses: Object.entries(op.responses ?? {}).map(([status, response]) => {
+      const firstMedia = firstResponseSchema(op, response);
+      return {
+        status,
+        description: response.description || '',
+        contentType: firstMedia?.contentType || 'application/json',
+        fields: firstMedia?.schema ? schemaToManualFields(doc, firstMedia.schema) : [],
+      };
+    }),
+  };
+}
+
+export function buildApiCliText(doc: SwaggerDocument, endpoint: Endpoint) {
+  return formatManualApiCliConfig(endpointToManualApiOperationConfig(doc, endpoint));
+}
+
+export function buildRawSchemaJson(endpoint: Endpoint) {
+  return JSON.stringify(
+    {
+      method: endpoint.method.toUpperCase(),
+      path: endpoint.path,
+      tags: endpoint.tags,
+      summary: endpoint.summary,
+      operation: endpoint.operation,
+    },
+    null,
+    2,
+  );
+}
+
+function rowToManualField(row: FieldRow): ManualApiFieldConfig {
+  return {
+    name: row.path || row.name,
+    location: normalizeFieldLocation(row.location),
+    required: row.required,
+    type: normalizeFieldType(row.type),
+    description: row.description || '',
+    defaultValue: row.defaultValue || '',
+    enumValue: row.enumValue || '',
+  };
+}
+
+function firstRequestBodySchema(operation: SwaggerOperation) {
+  const content = operation.requestBody?.content ?? {};
+  const firstContent = Object.entries(content)[0];
+  if (firstContent?.[1].schema) {
+    return {
+      required: Boolean(operation.requestBody?.required),
+      contentType: firstContent[0],
+      schema: firstContent[1].schema,
+    };
+  }
+
+  const bodyParameter = operation.parameters?.find((parameter) => parameter.in === 'body');
+  if (!bodyParameter?.schema) return undefined;
+  return {
+    required: Boolean(bodyParameter.required),
+    contentType: operation.consumes?.find((mediaType) => mediaType.includes('json')) ?? operation.consumes?.[0] ?? 'application/json',
+    schema: bodyParameter.schema,
+  };
+}
+
+function firstResponseSchema(
+  operation: SwaggerOperation,
+  response: NonNullable<SwaggerOperation['responses']>[string],
+) {
+  const firstContent = Object.entries(response.content ?? {})[0];
+  if (firstContent?.[1].schema) {
+    return {
+      contentType: firstContent[0],
+      schema: firstContent[1].schema,
+    };
+  }
+
+  const schema = response.schema ?? response.responseSchema;
+  if (!schema) return undefined;
+  return {
+    contentType: operation.produces?.find((mediaType) => mediaType.includes('json')) ?? operation.produces?.[0] ?? 'application/json',
+    schema,
+  };
+}
+
+function schemaToManualFields(doc: SwaggerDocument, schema: SwaggerSchema, seen = new Set<string>()): ManualApiFieldConfig[] {
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) return [];
+    const nextSeen = new Set(seen);
+    nextSeen.add(schema.$ref);
+    return schemaToManualFields(doc, resolved, nextSeen);
+  }
+
+  if (resolved.type === 'array') {
+    return [
+      {
+        name: 'items',
+        location: 'body',
+        type: 'array',
+        description: schemaDescription(schema) || schemaDescription(resolved),
+        children: resolved.items ? schemaToManualFields(doc, resolved.items, seen) : [],
+      },
+    ];
+  }
+
+  return Object.entries(resolved.properties ?? {}).map(([name, property]) =>
+    schemaPropertyToManualField(doc, name, property, (resolved.required ?? []).includes(name), seen),
+  );
+}
+
+function schemaPropertyToManualField(
+  doc: SwaggerDocument,
+  name: string,
+  schema: SwaggerSchema,
+  required: boolean,
+  seen: Set<string>,
+): ManualApiFieldConfig {
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  const type = manualFieldType(doc, schema);
+  const field: ManualApiFieldConfig = {
+    name,
+    location: 'body',
+    required,
+    type,
+    format: resolved.format || schema.format || '',
+    description: schemaDescription(schema) || schemaDescription(resolved),
+    defaultValue: resolved.default === undefined ? '' : formatValue(resolved.default),
+    enumValue: resolved.enum?.map(formatValue).join(', ') ?? '',
+  };
+
+  if (type === 'object') {
+    field.children = schema.$ref && seen.has(schema.$ref) ? [] : schemaToManualFields(doc, resolved, nextSeen(schema, seen));
+  }
+
+  if (type === 'array') {
+    const item = resolved.items;
+    field.children = item ? schemaToManualFields(doc, item, nextSeen(schema, seen)) : [];
+  }
+
+  return field;
+}
+
+function nextSeen(schema: SwaggerSchema, seen: Set<string>) {
+  if (!schema.$ref) return seen;
+  const next = new Set(seen);
+  next.add(schema.$ref);
+  return next;
+}
+
+function manualFieldType(doc: SwaggerDocument, schema: SwaggerSchema) {
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  if (resolved.type === 'array') return 'array';
+  if (resolved.type === 'object' || resolved.properties || schema.$ref) return 'object';
+  if (resolved.type === 'integer') return 'integer';
+  if (resolved.type === 'number') return 'number';
+  if (resolved.type === 'boolean') return 'boolean';
+  return 'string';
+}
+
+function normalizeFieldLocation(value?: string): ManualApiFieldConfig['location'] {
+  if (value === 'path' || value === 'query' || value === 'header' || value === 'cookie' || value === 'body') return value;
+  return 'body';
+}
+
+function normalizeFieldType(value: string) {
+  const normalized = value.toLowerCase();
+  if (normalized.includes('[]') || normalized.includes('array')) return 'array';
+  if (normalized.includes('object')) return 'object';
+  if (normalized.includes('integer')) return 'integer';
+  if (normalized.includes('number')) return 'number';
+  if (normalized.includes('boolean')) return 'boolean';
+  return 'string';
+}
+
+function operationHasBody(operation: SwaggerOperation) {
+  return Boolean(operation.requestBody) || Boolean(operation.parameters?.some((parameter) => parameter.in === 'body'));
+}
+
+function sortedEntries<T>(record: Record<string, T>) {
+  return Object.entries(record).sort(([left], [right]) => left.localeCompare(right, undefined, { sensitivity: 'base' }));
+}
+
+function sortFieldRows(rows: FieldRow[]) {
+  return [...rows].sort((left, right) => {
+    const leftKey = left.path || left.name;
+    const rightKey = right.path || right.name;
+    return leftKey.localeCompare(rightKey, undefined, { sensitivity: 'base' });
+  });
+}
+
+function parameterSchema(parameter: SwaggerParameter): SwaggerSchema | undefined {
+  if (parameter.schema) return parameter.schema;
+  if (!parameter.type && !parameter.format && !parameter.items && !parameter.enum?.length && parameter.default === undefined) return undefined;
+  return {
+    type: parameter.type,
+    format: parameter.format,
+    items: parameter.items,
+    enum: parameter.enum,
+    default: parameter.default,
+    description: parameter.description,
+  };
+}
+
+function rowsToMarkdown(rows: FieldRow[], emptyText: string) {
+  if (!rows.length) return emptyText;
+
+  return [
+    '| 字段 | 位置 | 必填 | 类型 | 默认值 | 枚举 | 说明 |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+    ...rows.map((row) => {
+      const indent = row.depth > 0 ? `${'  '.repeat(row.depth)}${row.name}` : row.name;
+      return [
+        escapeCell(indent),
+        escapeCell(row.location || '-'),
+        row.required ? '是' : '否',
+        escapeCell(row.type),
+        escapeCell(row.defaultValue || '-'),
+        escapeCell(row.enumValue || '-'),
+        escapeCell(row.description || '-'),
+      ].join(' | ');
+    }),
+  ]
+    .map((line) => (line.startsWith('|') ? line : `| ${line} |`))
+    .join('\n');
+}
+
+function toRow(
+  doc: SwaggerDocument,
+  name: string,
+  path: string,
+  schema: SwaggerSchema,
+  required: boolean,
+  depth: number,
+  location?: string,
+): FieldRow {
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  return {
+    name,
+    path,
+    location,
+    required,
+    type: schemaType(doc, schema),
+    description: schemaDescription(schema) || schemaDescription(resolved),
+    defaultValue: resolved.default === undefined ? '' : formatValue(resolved.default),
+    enumValue: resolved.enum?.map(formatValue).join(', ') ?? '',
+    depth,
+  };
+}
+
+function formatValue(value: unknown) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  const json = JSON.stringify(value);
+  return json === undefined ? String(value) : json;
+}
+
+function escapeCell(value: unknown) {
+  return String(value ?? '').replace(/\|/g, '\\|').replace(/\n/g, '<br />');
+}