mirror of
https://github.com/labring/FastGPT.git
synced 2025-10-20 18:54:09 +00:00
chore: openapi doc generator (#2644)
* chore: extract the type and comment from apis * chore: template code * feat: openapi * pref: openapi generator. send into public/openapi folder
This commit is contained in:
223
scripts/openapi/utils.ts
Normal file
223
scripts/openapi/utils.ts
Normal file
@@ -0,0 +1,223 @@
|
||||
import type { TSType, TSTypeLiteral } from '@babel/types';
|
||||
import { parse } from '@babel/parser';
|
||||
import traverse, { NodePath } from '@babel/traverse';
|
||||
import * as fs from 'fs';
|
||||
import type { ApiMetaData, ApiType, itemType } from './type';
|
||||
|
||||
function getMetadata(path: NodePath): ApiMetaData | undefined {
|
||||
const metadata = {
|
||||
name: '',
|
||||
author: '',
|
||||
version: '',
|
||||
method: ''
|
||||
};
|
||||
if (
|
||||
path.isExportNamedDeclaration() && // get metadata
|
||||
path.node.declaration?.type === 'VariableDeclaration' &&
|
||||
path.node.declaration.declarations[0]?.id.type === 'Identifier' &&
|
||||
path.node.declaration.declarations[0].id.name === 'ApiMetadata' &&
|
||||
path.node.declaration.declarations[0].init?.type === 'ObjectExpression'
|
||||
) {
|
||||
path.node.declaration.declarations[0].init.properties.forEach((item) => {
|
||||
if (item.type === 'ObjectProperty') {
|
||||
const key = item.key.type === 'Identifier' ? item.key.name : item.key.type;
|
||||
if (key === 'name') {
|
||||
metadata.name = item.value.type === 'StringLiteral' ? item.value.value : item.value.type;
|
||||
}
|
||||
if (key === 'author') {
|
||||
metadata.author =
|
||||
item.value.type === 'StringLiteral' ? item.value.value : item.value.type;
|
||||
}
|
||||
if (key === 'version') {
|
||||
metadata.version =
|
||||
item.value.type === 'StringLiteral' ? item.value.value : item.value.type;
|
||||
} else if (key === 'method') {
|
||||
metadata.method =
|
||||
item.value.type === 'StringLiteral' ? item.value.value : item.value.type;
|
||||
metadata.method = metadata.method.toUpperCase();
|
||||
}
|
||||
}
|
||||
});
|
||||
if (metadata.name && metadata.author && metadata.version) {
|
||||
return metadata;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function getDescription(path: NodePath) {
|
||||
if (path.isFunctionDeclaration() && path.node.id?.name === 'handler') {
|
||||
const comments = path.node.leadingComments?.map((item) => item.value.trim()).join('\n');
|
||||
return comments;
|
||||
}
|
||||
}
|
||||
|
||||
type ApiDataType = {
|
||||
type?: 'query' | 'body' | 'response';
|
||||
comment?: string;
|
||||
items?: itemType[];
|
||||
dataType?: string;
|
||||
};
|
||||
|
||||
function parseType(type?: TSType): string {
|
||||
if (!type) {
|
||||
return '';
|
||||
}
|
||||
if (type.type === 'TSTypeReference') {
|
||||
return type.typeName.type === 'Identifier' ? type.typeName.name : type.typeName.type;
|
||||
} else if (type.type === 'TSArrayType') {
|
||||
return `${parseType(type.elementType)}[]`;
|
||||
} else if (type.type === 'TSUnionType') {
|
||||
return type.types.map((item) => parseType(item)).join(' | ');
|
||||
} else if (type.type === 'TSIntersectionType') {
|
||||
return type.types.map((item) => parseType(item)).join(' & ');
|
||||
} else if (type.type === 'TSLiteralType') {
|
||||
return type.literal.type === 'StringLiteral' ? type.literal.value : type.literal.type;
|
||||
// } else if (type.type === 'TSTypeLiteral') {
|
||||
// return parseTypeLiteral(type);
|
||||
} else if (type.type === 'TSStringKeyword') {
|
||||
return 'string';
|
||||
} else if (type.type === 'TSNumberKeyword') {
|
||||
return 'number';
|
||||
} else if (type.type === 'TSBooleanKeyword') {
|
||||
return 'boolean';
|
||||
} else {
|
||||
return type.type;
|
||||
}
|
||||
}
|
||||
|
||||
function parseTypeLiteral(type: TSTypeLiteral): itemType[] {
|
||||
const items: itemType[] = [];
|
||||
type.members.forEach((item) => {
|
||||
if (item.type === 'TSPropertySignature') {
|
||||
const key = item.key.type === 'Identifier' ? item.key.name : item.key.type;
|
||||
const value = parseType(item.typeAnnotation?.typeAnnotation);
|
||||
const comments = [
|
||||
item.leadingComments?.map((item) => item.value.trim()).join('\n'),
|
||||
item.trailingComments?.map((item) => item.value.trim()).join('\n')
|
||||
].join('\n');
|
||||
const required = item.optional ? false : true;
|
||||
items.push({
|
||||
type: value,
|
||||
comment: comments,
|
||||
key,
|
||||
required
|
||||
});
|
||||
}
|
||||
});
|
||||
return items;
|
||||
}
|
||||
|
||||
function getData(path: NodePath): ApiDataType | undefined {
|
||||
const type: ApiDataType = {};
|
||||
if (path.isExportNamedDeclaration()) {
|
||||
const comments = [
|
||||
path.node.leadingComments?.map((item) => item.value.trim()).join('\n'),
|
||||
path.node.trailingComments?.map((item) => item.value.trim()).join('\n')
|
||||
].join('\n');
|
||||
if (comments) {
|
||||
type.comment = comments;
|
||||
}
|
||||
if (path.node.declaration?.type === 'TSTypeAliasDeclaration') {
|
||||
if (path.node.declaration.id.type === 'Identifier') {
|
||||
if (path.node.declaration.id.name.endsWith('Query')) {
|
||||
type.type = 'query';
|
||||
const queryType = path.node.declaration.typeAnnotation;
|
||||
if (queryType) {
|
||||
if (queryType.type === 'TSTypeLiteral') {
|
||||
type.items = parseTypeLiteral(queryType);
|
||||
} else {
|
||||
type.dataType = parseType(queryType);
|
||||
}
|
||||
}
|
||||
} else if (path.node.declaration.id.name.endsWith('Body')) {
|
||||
type.type = 'body';
|
||||
if (path.node.declaration.typeAnnotation) {
|
||||
if (path.node.declaration.typeAnnotation.type === 'TSTypeLiteral') {
|
||||
type.items = parseTypeLiteral(path.node.declaration.typeAnnotation);
|
||||
} else {
|
||||
type.dataType = parseType(path.node.declaration.typeAnnotation);
|
||||
}
|
||||
}
|
||||
} else if (path.node.declaration.id.name.endsWith('Response')) {
|
||||
type.type = 'response';
|
||||
if (path.node.declaration.typeAnnotation) {
|
||||
if (path.node.declaration.typeAnnotation.type === 'TSTypeLiteral') {
|
||||
type.items = parseTypeLiteral(path.node.declaration.typeAnnotation);
|
||||
} else {
|
||||
type.dataType = parseType(path.node.declaration.typeAnnotation);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return type;
|
||||
}
|
||||
|
||||
function parseCode(code: string): ApiType {
|
||||
const ast = parse(code, {
|
||||
sourceType: 'module',
|
||||
plugins: ['typescript', 'jsx']
|
||||
});
|
||||
|
||||
const api = <ApiType>{};
|
||||
|
||||
traverse(ast, {
|
||||
enter(path) {
|
||||
const metadata = getMetadata(path);
|
||||
const description = getDescription(path);
|
||||
const data = getData(path);
|
||||
if (metadata) {
|
||||
api.name = metadata.name;
|
||||
api.author = metadata.author;
|
||||
api.version = metadata.version;
|
||||
}
|
||||
if (description) {
|
||||
api.description = description;
|
||||
}
|
||||
if (data) {
|
||||
if (data.type === 'query') {
|
||||
api.query = data.items ?? {
|
||||
type: data.dataType ?? '',
|
||||
comment: data.comment ?? ''
|
||||
};
|
||||
} else if (data.type === 'body') {
|
||||
api.body = data.items ?? {
|
||||
type: data.dataType ?? '',
|
||||
comment: data.comment ?? ''
|
||||
};
|
||||
} else if (data.type === 'response') {
|
||||
api.response = data.items ?? {
|
||||
type: data.dataType ?? '',
|
||||
comment: data.comment ?? ''
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
return api;
|
||||
}
|
||||
|
||||
function getMethod(api: ApiType): 'GET' | 'POST' {
|
||||
if (api.query && !(Array.isArray(api.query) && api.query.length === 0)) {
|
||||
return 'GET';
|
||||
} else if (api.body && !(Array.isArray(api.body) && api.body.length === 0)) {
|
||||
return 'POST';
|
||||
} else {
|
||||
return 'GET';
|
||||
}
|
||||
}
|
||||
|
||||
export function parseAPI({ path, rootPath }: { path: string; rootPath: string }): ApiType {
|
||||
const code = fs.readFileSync(path, 'utf-8');
|
||||
const api = parseCode(code);
|
||||
api.url = path.replace('.ts', '').replace(rootPath, '');
|
||||
api.path = path;
|
||||
if (api.method === undefined) {
|
||||
api.method = getMethod(api);
|
||||
}
|
||||
return api;
|
||||
}
|
Reference in New Issue
Block a user