제24강: 문서화 자동화와 API 스펙 생성

AI 기반 문서 자동 생성 시스템

// tools/AIDocumentationGenerator.ts
import { CursorAI } from '@cursor/api';
import { Project, SourceFile, ClassDeclaration, FunctionDeclaration } from 'ts-morph';
import * as fs from 'fs/promises';
import * as path from 'path';
import { marked } from 'marked';

export class AIDocumentationGenerator {
    private cursor: CursorAI;
    private project: Project;
    private config: DocGeneratorConfig;

    constructor(config: DocGeneratorConfig) {
        this.cursor = new CursorAI();
        this.project = new Project({
            tsConfigFilePath: config.tsConfigPath,
            skipAddingFilesFromTsConfig: false
        });
        this.config = config;
    }

    async generateDocumentation(): Promise {
        const docs: Documentation = {
            overview: await this.generateOverview(),
            modules: await this.generateModuleDocs(),
            api: await this.generateAPIDocs(),
            examples: await this.generateExamples(),
            guides: await this.generateGuides(),
            changelog: await this.generateChangelog()
        };

        // 문서 렌더링
        await this.renderDocumentation(docs);
        
        // 다국어 번역
        if (this.config.languages?.length > 0) {
            await this.translateDocumentation(docs);
        }

        return docs;
    }

    async generateOverview(): Promise {
        const projectFiles = this.project.getSourceFiles();
        
        const prompt = `
프로젝트 구조를 분석하여 포괄적인 개요 문서를 작성해주세요:

파일 수: ${projectFiles.length}
주요 디렉토리: ${this.getMainDirectories()}

다음 내용을 포함해주세요:
1. 프로젝트 목적과 주요 기능
2. 아키텍처 개요
3. 핵심 컴포넌트 설명
4. 기술 스택
5. 시작하기 가이드
`;

        const response = await this.cursor.ai.generateCode(prompt);
        
        return {
            title: this.config.projectName,
            description: response,
            architecture: await this.generateArchitectureDiagram(),
            techStack: await this.detectTechStack(),
            quickStart: await this.generateQuickStart()
        };
    }

    async generateModuleDocs(): Promise {
        const modules: ModuleDocumentation[] = [];
        const sourceFiles = this.project.getSourceFiles();

        for (const file of sourceFiles) {
            const module = await this.documentModule(file);
            if (module) {
                modules.push(module);
            }
        }

        return modules;
    }

    async documentModule(file: SourceFile): Promise {
        const filePath = file.getFilePath();
        
        // 테스트 파일이나 설정 파일은 제외
        if (this.shouldSkipFile(filePath)) {
            return null;
        }

        const classes = file.getClasses();
        const functions = file.getFunctions();
        const interfaces = file.getInterfaces();
        const enums = file.getEnums();

        if (classes.length === 0 && functions.length === 0 && 
            interfaces.length === 0 && enums.length === 0) {
            return null;
        }

        const moduleDoc: ModuleDocumentation = {
            name: path.basename(filePath, path.extname(filePath)),
            path: filePath,
            description: await this.generateModuleDescription(file),
            exports: {
                classes: await Promise.all(classes.map(c => this.documentClass(c))),
                functions: await Promise.all(functions.map(f => this.documentFunction(f))),
                interfaces: await Promise.all(interfaces.map(i => this.documentInterface(i))),
                enums: await Promise.all(enums.map(e => this.documentEnum(e)))
            },
            examples: await this.generateModuleExamples(file),
            dependencies: this.extractDependencies(file)
        };

        return moduleDoc;
    }

    async documentClass(classDecl: ClassDeclaration): Promise {
        const className = classDecl.getName() || 'Anonymous';
        const methods = classDecl.getMethods();
        const properties = classDecl.getProperties();
        const constructor = classDecl.getConstructors()[0];

        // 기존 JSDoc 추출
        const existingDoc = this.extractJSDoc(classDecl);

        // AI로 문서 보강
        const enhancedDoc = await this.enhanceDocumentation(
            className,
            classDecl.getText(),
            existingDoc
        );

        return {
            name: className,
            description: enhancedDoc.description,
            extends: classDecl.getExtends()?.getText(),
            implements: classDecl.getImplements().map(i => i.getText()),
            constructor: constructor ? await this.documentConstructor(constructor) : undefined,
            properties: await Promise.all(properties.map(p => this.documentProperty(p))),
            methods: await Promise.all(methods.map(m => this.documentMethod(m))),
            examples: enhancedDoc.examples,
            usage: enhancedDoc.usage,
            relatedClasses: await this.findRelatedClasses(classDecl)
        };
    }

    async documentFunction(func: FunctionDeclaration): Promise {
        const funcName = func.getName() || 'Anonymous';
        const parameters = func.getParameters();
        const returnType = func.getReturnType();

        const prompt = `
함수를 분석하여 문서를 작성해주세요:

함수명: ${funcName}
코드:
\`\`\`typescript
${func.getText()}
\`\`\`

다음을 포함해주세요:
1. 함수의 목적과 동작 설명
2. 각 매개변수의 상세 설명
3. 반환값 설명
4. 사용 예제 (2-3개)
5. 예외 상황과 에러 처리
6. 복잡도와 성능 고려사항
`;

        const aiDoc = await this.cursor.ai.generateCode(prompt);
        const parsedDoc = this.parseAIDocumentation(aiDoc);

        return {
            name: funcName,
            description: parsedDoc.description,
            parameters: parameters.map((param, index) => ({
                name: param.getName(),
                type: param.getType().getText(),
                description: parsedDoc.parameters?.[index]?.description || '',
                optional: param.isOptional(),
                default: param.getInitializer()?.getText()
            })),
            returns: {
                type: returnType.getText(),
                description: parsedDoc.returns?.description || ''
            },
            throws: parsedDoc.throws || [],
            examples: parsedDoc.examples || [],
            complexity: this.calculateComplexity(func),
            sideEffects: parsedDoc.sideEffects || [],
            relatedFunctions: await this.findRelatedFunctions(func)
        };
    }

    async generateAPIDocs(): Promise {
        const apiEndpoints = await this.detectAPIEndpoints();
        const openApiSpec = await this.generateOpenAPISpec(apiEndpoints);

        return {
            openapi: openApiSpec,
            endpoints: await Promise.all(
                apiEndpoints.map(endpoint => this.documentEndpoint(endpoint))
            ),
            authentication: await this.documentAuthentication(),
            rateLimiting: await this.documentRateLimiting(),
            errors: await this.documentErrorResponses(),
            webhooks: await this.documentWebhooks(),
            postmanCollection: await this.generatePostmanCollection(apiEndpoints)
        };
    }

    async generateOpenAPISpec(endpoints: APIEndpoint[]): Promise {
        const spec: OpenAPISpec = {
            openapi: '3.1.0',
            info: {
                title: this.config.projectName,
                version: this.config.version || '1.0.0',
                description: await this.generateAPIDescription(),
                contact: this.config.contact,
                license: this.config.license
            },
            servers: this.config.servers || [],
            paths: {},
            components: {
                schemas: {},
                securitySchemes: {},
                parameters: {},
                responses: {}
            },
            security: []
        };

        // 각 엔드포인트를 OpenAPI 경로로 변환
        for (const endpoint of endpoints) {
            const path = endpoint.path;
            if (!spec.paths[path]) {
                spec.paths[path] = {};
            }

            spec.paths[path][endpoint.method.toLowerCase()] = {
                summary: endpoint.summary,
                description: endpoint.description,
                operationId: endpoint.operationId,
                tags: endpoint.tags,
                parameters: await this.generateParameters(endpoint),
                requestBody: await this.generateRequestBody(endpoint),
                responses: await this.generateResponses(endpoint),
                security: endpoint.security || []
            };
        }

        // 스키마 자동 생성
        spec.components.schemas = await this.generateSchemas();

        return spec;
    }

    async documentEndpoint(endpoint: APIEndpoint): Promise {
        const prompt = `
API 엔드포인트를 분석하여 상세 문서를 작성해주세요:

경로: ${endpoint.method} ${endpoint.path}
핸들러 코드:
\`\`\`typescript
${endpoint.handler}
\`\`\`

다음 내용을 포함해주세요:
1. 엔드포인트의 목적과 기능
2. 요청 매개변수 상세 설명
3. 요청 본문 형식과 예제
4. 응답 형식과 상태 코드
5. 인증 요구사항
6. 사용 예제 (cURL, JavaScript, Python)
7. 일반적인 에러 시나리오
`;

        const aiDoc = await this.cursor.ai.generateCode(prompt);
        const examples = await this.generateAPIExamples(endpoint);

        return {
            ...endpoint,
            detailedDescription: aiDoc,
            examples: {
                curl: examples.curl,
                javascript: examples.javascript,
                python: examples.python,
                go: examples.go
            },
            testing: {
                unitTests: await this.generateEndpointTests(endpoint),
                integrationTests: await this.generateIntegrationTests(endpoint)
            },
            performance: {
                expectedLatency: await this.estimateLatency(endpoint),
                rateLimit: endpoint.rateLimit,
                caching: endpoint.caching
            }
        };
    }

    async generateExamples(): Promise {
        const examples: ExampleCollection = {
            quickStart: [],
            useCases: [],
            integrations: [],
            troubleshooting: []
        };

        // 빠른 시작 예제
        examples.quickStart.push({
            title: '기본 설정',
            description: '프로젝트 초기 설정 방법',
            code: await this.generateQuickStartExample(),
            language: 'typescript'
        });

        // 사용 사례별 예제
        const useCases = await this.detectUseCases();
        for (const useCase of useCases) {
            examples.useCases.push({
                title: useCase.title,
                description: useCase.description,
                code: await this.generateUseCaseExample(useCase),
                explanation: await this.explainExample(useCase)
            });
        }

        // 통합 예제
        examples.integrations = await this.generateIntegrationExamples();

        // 문제 해결 가이드
        examples.troubleshooting = await this.generateTroubleshootingGuides();

        return examples;
    }

    async generateGuides(): Promise {
        const guides: GuideCollection = {
            gettingStarted: await this.generateGettingStartedGuide(),
            architecture: await this.generateArchitectureGuide(),
            bestPractices: await this.generateBestPracticesGuide(),
            deployment: await this.generateDeploymentGuide(),
            migration: await this.generateMigrationGuide(),
            contributing: await this.generateContributingGuide()
        };

        return guides;
    }

    async generateArchitectureGuide(): Promise {
        const prompt = `
프로젝트의 아키텍처 가이드를 작성해주세요:

프로젝트 구조:
${this.getProjectStructure()}

다음 내용을 포함해주세요:
1. 전체 시스템 아키텍처
2. 주요 컴포넌트와 책임
3. 데이터 흐름
4. 디자인 패턴과 원칙
5. 확장성 고려사항
6. 보안 아키텍처
7. 성능 최적화 전략
`;

        const aiGuide = await this.cursor.ai.generateCode(prompt);
        
        return {
            overview: aiGuide,
            diagrams: await this.generateArchitectureDiagrams(),
            components: await this.documentComponents(),
            patterns: await this.documentDesignPatterns(),
            dataFlow: await this.documentDataFlow(),
            security: await this.documentSecurityArchitecture(),
            scalability: await this.documentScalabilityConsiderations()
        };
    }

    async renderDocumentation(docs: Documentation): Promise {
        const outputDir = this.config.outputDir || './docs';
        
        // 디렉토리 구조 생성
        await this.createDocumentationStructure(outputDir);

        // 메인 문서 렌더링
        await this.renderMainDocumentation(docs, outputDir);

        // API 문서 렌더링
        await this.renderAPIDocumentation(docs.api, path.join(outputDir, 'api'));

        // 가이드 렌더링
        await this.renderGuides(docs.guides, path.join(outputDir, 'guides'));

        // 인터랙티브 문서 생성
        if (this.config.interactive) {
            await this.generateInteractiveDocs(docs, outputDir);
        }

        // 검색 인덱스 생성
        await this.generateSearchIndex(docs, outputDir);
    }

    async generateInteractiveDocs(docs: Documentation, outputDir: string): Promise {
        // Docusaurus 설정 생성
        const docusaurusConfig = {
            title: this.config.projectName,
            tagline: docs.overview.description.split('\n')[0],
            url: this.config.url || 'https://example.com',
            baseUrl: this.config.baseUrl || '/',
            onBrokenLinks: 'throw',
            onBrokenMarkdownLinks: 'warn',
            favicon: 'img/favicon.ico',
            organizationName: this.config.organization,
            projectName: this.config.projectName,
            
            presets: [
                [
                    'classic',
                    {
                        docs: {
                            sidebarPath: require.resolve('./sidebars.js'),
                            editUrl: this.config.editUrl
                        },
                        blog: false,
                        theme: {
                            customCss: require.resolve('./src/css/custom.css')
                        }
                    }
                ]
            ],

            themeConfig: {
                navbar: {
                    title: this.config.projectName,
                    items: [
                        {
                            type: 'doc',
                            docId: 'intro',
                            position: 'left',
                            label: '문서'
                        },
                        {
                            to: '/api',
                            label: 'API',
                            position: 'left'
                        },
                        {
                            href: this.config.githubUrl,
                            label: 'GitHub',
                            position: 'right'
                        }
                    ]
                },
                footer: {
                    style: 'dark',
                    copyright: `Copyright © ${new Date().getFullYear()} ${this.config.organization}`
                },
                prism: {
                    theme: lightCodeTheme,
                    darkTheme: darkCodeTheme,
                    additionalLanguages: ['typescript', 'javascript', 'python', 'go']
                }
            }
        };

        // Docusaurus 프로젝트 생성
        await this.createDocusaurusProject(docusaurusConfig, outputDir);
        
        // API 플레이그라운드 생성
        await this.createAPIPlayground(docs.api, path.join(outputDir, 'static', 'api-playground'));
    }

    async translateDocumentation(docs: Documentation): Promise {
        const languages = this.config.languages || [];
        
        for (const lang of languages) {
            const translatedDocs = await this.translateToLanguage(docs, lang);
            await this.renderDocumentation(translatedDocs);
        }
    }

    async translateToLanguage(docs: Documentation, targetLang: string): Promise {
        const prompt = `
다음 기술 문서를 ${targetLang}로 번역해주세요.
기술 용어는 적절히 현지화하되, 코드와 API 이름은 그대로 유지해주세요.

원본:
${JSON.stringify(docs, null, 2)}
`;

        const translatedContent = await this.cursor.ai.generateCode(prompt);
        return JSON.parse(translatedContent);
    }

    async generateSearchIndex(docs: Documentation, outputDir: string): Promise {
        const searchIndex = [];
        
        // 모든 문서에서 검색 가능한 콘텐츠 추출
        this.extractSearchableContent(docs, searchIndex);
        
        // Algolia DocSearch 호환 인덱스 생성
        const algoliaIndex = {
            index_name: this.config.projectName,
            start_urls: [this.config.url],
            selectors: {
                lvl0: '.doc h1',
                lvl1: '.doc h2',
                lvl2: '.doc h3',
                text: '.doc p, .doc li'
            }
        };

        await fs.writeFile(
            path.join(outputDir, 'search-index.json'),
            JSON.stringify(searchIndex, null, 2)
        );

        await fs.writeFile(
            path.join(outputDir, 'algolia-config.json'),
            JSON.stringify(algoliaIndex, null, 2)
        );
    }
}

// 자동 문서화 워크플로우
export async function generateProjectDocumentation() {
    const generator = new AIDocumentationGenerator({
        projectName: 'My Awesome Project',
        tsConfigPath: './tsconfig.json',
        outputDir: './docs',
        interactive: true,
        languages: ['ko', 'ja', 'zh'],
        servers: [
            { url: 'https://api.example.com', description: 'Production' },
            { url: 'https://staging-api.example.com', description: 'Staging' }
        ]
    });

    console.log('📚 문서 생성 시작...');
    const docs = await generator.generateDocumentation();
    
    console.log('✅ 문서 생성 완료!');
    console.log(`📁 출력 위치: ${generator.config.outputDir}`);
    
    // 문서 미리보기 서버 실행
    if (generator.config.preview) {
        await startDocumentationServer(generator.config.outputDir);
    }
}