docs: add migration documentation, finalization scripts, and update Swagger paths
This commit is contained in:
@@ -0,0 +1,322 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Post-Migration Script: Update documentation and references
|
||||
*
|
||||
* This script handles post-migration tasks:
|
||||
* 1. Update Swagger YAML documentation files
|
||||
* 2. Update app.js if needed
|
||||
* 3. Update Postman collection files
|
||||
* 4. Update other references to v1/v2/v3
|
||||
*
|
||||
* Usage: node scripts/update-references-post-migration.js
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const { execSync } = require('child_process');
|
||||
|
||||
const colors = {
|
||||
reset: '\x1b[0m',
|
||||
green: '\x1b[32m',
|
||||
yellow: '\x1b[33m',
|
||||
red: '\x1b[31m',
|
||||
cyan: '\x1b[36m',
|
||||
blue: '\x1b[34m',
|
||||
};
|
||||
|
||||
const log = {
|
||||
info: (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`),
|
||||
success: (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`),
|
||||
warn: (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`),
|
||||
error: (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`),
|
||||
section: (msg) => console.log(`\n${colors.blue}━━━ ${msg} ━━━${colors.reset}\n`),
|
||||
};
|
||||
|
||||
const projectRoot = path.resolve(__dirname, '..');
|
||||
const swaggerDir = path.join(projectRoot, 'src/swagger');
|
||||
|
||||
/**
|
||||
* Phase 1: Update Swagger YAML files
|
||||
*/
|
||||
function updateSwaggerYaml() {
|
||||
log.section('Phase 1: Updating Swagger YAML files');
|
||||
|
||||
const pathMappings = {
|
||||
'/api/v1': '/api/skydive',
|
||||
'/api/v2': '/api/cms',
|
||||
'/api/v3': '/api/herowars',
|
||||
};
|
||||
|
||||
if (!fs.existsSync(swaggerDir)) {
|
||||
log.warn(`Swagger directory not found: ${swaggerDir}`);
|
||||
return;
|
||||
}
|
||||
|
||||
const yamlFiles = fs.readdirSync(swaggerDir).filter((f) => f.endsWith('.yaml'));
|
||||
|
||||
yamlFiles.forEach((file) => {
|
||||
const filePath = path.join(swaggerDir, file);
|
||||
let content = fs.readFileSync(filePath, 'utf8');
|
||||
let modified = false;
|
||||
|
||||
Object.entries(pathMappings).forEach(([oldPath, newPath]) => {
|
||||
if (content.includes(oldPath)) {
|
||||
const regex = new RegExp(oldPath, 'g');
|
||||
content = content.replace(regex, newPath);
|
||||
modified = true;
|
||||
}
|
||||
});
|
||||
|
||||
if (modified) {
|
||||
fs.writeFileSync(filePath, content);
|
||||
log.success(`Updated: ${file}`);
|
||||
} else {
|
||||
log.info(`No changes needed: ${file}`);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Phase 2: Update Postman collection and environment
|
||||
*/
|
||||
function updatePostmanFiles() {
|
||||
log.section('Phase 2: Updating Postman files');
|
||||
|
||||
const testsDir = path.join(projectRoot, 'tests');
|
||||
const collectionPath = path.join(testsDir, 'adastra-api-tests.postman_collection.json');
|
||||
const environmentPath = path.join(testsDir, 'adastra-api-tests.postman_environment.json');
|
||||
|
||||
const updateJsonFile = (filePath, description) => {
|
||||
if (!fs.existsSync(filePath)) {
|
||||
log.warn(`File not found: ${description}`);
|
||||
return;
|
||||
}
|
||||
|
||||
let content = fs.readFileSync(filePath, 'utf8');
|
||||
let modified = false;
|
||||
|
||||
const pathMappings = [
|
||||
{ old: '/api/v1/', new: '/api/skydive/' },
|
||||
{ old: '/api/v2/', new: '/api/cms/' },
|
||||
{ old: '/api/v3/', new: '/api/herowars/' },
|
||||
];
|
||||
|
||||
pathMappings.forEach(({ old, new: newPath }) => {
|
||||
if (content.includes(old)) {
|
||||
const regex = new RegExp(old, 'g');
|
||||
content = content.replace(regex, newPath);
|
||||
modified = true;
|
||||
}
|
||||
});
|
||||
|
||||
if (modified) {
|
||||
fs.writeFileSync(filePath, content);
|
||||
log.success(`Updated: ${description}`);
|
||||
} else {
|
||||
log.info(`No changes needed: ${description}`);
|
||||
}
|
||||
};
|
||||
|
||||
updateJsonFile(collectionPath, 'Postman collection');
|
||||
updateJsonFile(environmentPath, 'Postman environment');
|
||||
}
|
||||
|
||||
/**
|
||||
* Phase 3: Check and report other references
|
||||
*/
|
||||
function findRemainingReferences() {
|
||||
log.section('Phase 3: Scanning for remaining v1/v2/v3 references');
|
||||
|
||||
const patterns = ['/api/v1', '/api/v2', '/api/v3', 'routes.use(\'/v1', 'routes.use(\'/v2', 'routes.use(\'/v3'];
|
||||
const ignorePatterns = ['node_modules', '.git', 'dist', 'build', 'v1/', 'v2/', 'v3/'];
|
||||
|
||||
const filesToCheck = [
|
||||
'app.js',
|
||||
'src/config/swagger.js',
|
||||
'README.md',
|
||||
'src/app.js',
|
||||
'.env*',
|
||||
];
|
||||
|
||||
log.info('Checking key files for old path references...\n');
|
||||
|
||||
let foundReferences = false;
|
||||
|
||||
filesToCheck.forEach((filePattern) => {
|
||||
// Handle glob patterns like .env*
|
||||
let filePaths = [];
|
||||
|
||||
if (filePattern.includes('*')) {
|
||||
const glob = path.basename(filePattern);
|
||||
const dir = path.dirname(filePattern);
|
||||
const basePath = dir === '.' ? projectRoot : path.join(projectRoot, dir);
|
||||
|
||||
if (fs.existsSync(basePath)) {
|
||||
const files = fs.readdirSync(basePath);
|
||||
files.forEach((f) => {
|
||||
if (new RegExp(`^${glob.replace(/\*/g, '.*')}$`).test(f)) {
|
||||
filePaths.push(path.join(basePath, f));
|
||||
}
|
||||
});
|
||||
}
|
||||
} else {
|
||||
const fullPath = filePattern.startsWith('/')
|
||||
? filePattern
|
||||
: path.join(projectRoot, filePattern);
|
||||
if (fs.existsSync(fullPath)) {
|
||||
filePaths.push(fullPath);
|
||||
}
|
||||
}
|
||||
|
||||
filePaths.forEach((filePath) => {
|
||||
try {
|
||||
const content = fs.readFileSync(filePath, 'utf8');
|
||||
const lines = content.split('\n');
|
||||
|
||||
patterns.forEach((pattern) => {
|
||||
lines.forEach((line, index) => {
|
||||
if (line.includes(pattern)) {
|
||||
foundReferences = true;
|
||||
const relativePath = path.relative(projectRoot, filePath);
|
||||
log.warn(`Found in [${relativePath}:${index + 1}]: ${line.trim()}`);
|
||||
}
|
||||
});
|
||||
});
|
||||
} catch (err) {
|
||||
// Silently skip files that can't be read
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
if (!foundReferences) {
|
||||
log.success('No remaining v1/v2/v3 references found in key files!');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Phase 4: Generate update checklist
|
||||
*/
|
||||
function generateUpdateChecklist() {
|
||||
log.section('Phase 4: Final checklist');
|
||||
|
||||
const checklist = `
|
||||
# Post-Migration Update Checklist
|
||||
|
||||
## Files Updated by Script ✓
|
||||
- [x] Swagger YAML files (/api/v1 → /api/skydive, etc.)
|
||||
- [x] Postman collection and environment files
|
||||
- [x] API routes structure (new domains created)
|
||||
|
||||
## Manual Verification Required
|
||||
|
||||
### 1. Test API Endpoints
|
||||
\`\`\`bash
|
||||
npm run local # Start the server
|
||||
# In another terminal:
|
||||
curl http://localhost:3200/api-docs # Check Swagger UI
|
||||
\`\`\`
|
||||
|
||||
### 2. Verify Routes
|
||||
- [ ] GET /api/skydive/jumps
|
||||
- [ ] GET /api/cms/articles
|
||||
- [ ] GET /api/herowars/clans
|
||||
- [ ] Other domain-specific endpoints
|
||||
|
||||
### 3. Frontend Updates Required (if applicable)
|
||||
- [ ] Update Angular environment files (environment.ts, environment.development.ts, etc.)
|
||||
- [ ] Replace all API calls from /api/v1, /api/v2, /api/v3 to new domains
|
||||
- [ ] Update service layer URLs
|
||||
- [ ] Update HTTP interceptors if needed
|
||||
|
||||
### 4. Documentation Updates
|
||||
- [ ] Update README.md with new API structure
|
||||
- [ ] Update API documentation (if any)
|
||||
- [ ] Update deployment/infrastructure docs
|
||||
- [ ] Update team wiki/documentation
|
||||
|
||||
### 5. CI/CD Pipeline (if applicable)
|
||||
- [ ] Update build/deployment scripts referencing v1/v2/v3
|
||||
- [ ] Update any health checks pointing to old paths
|
||||
- [ ] Update monitoring/alerting rules
|
||||
|
||||
### 6. Client Applications
|
||||
- [ ] Update all client libraries/SDKs
|
||||
- [ ] Update mobile app API endpoints
|
||||
- [ ] Update third-party integrations
|
||||
|
||||
### 7. Database/Caching (if applicable)
|
||||
- [ ] Clear any cached references to old endpoints
|
||||
- [ ] Update API documentation in databases
|
||||
- [ ] Check for hardcoded URLs in configuration
|
||||
|
||||
## Git Operations
|
||||
\`\`\`bash
|
||||
# View the migration commits
|
||||
git log --oneline -5
|
||||
|
||||
# If rollback needed:
|
||||
git revert <commit-hash>
|
||||
|
||||
# Push changes
|
||||
git push origin develop
|
||||
\`\`\`
|
||||
|
||||
## Optional: Cleanup Old Directories
|
||||
\`\`\`bash
|
||||
# After thorough testing, remove old v1/v2/v3 directories:
|
||||
rm -rf src/routes/api/v1
|
||||
rm -rf src/routes/api/v2
|
||||
rm -rf src/routes/api/v3
|
||||
git add -A
|
||||
git commit -m "chore: remove old v1/v2/v3 route directories"
|
||||
\`\`\`
|
||||
|
||||
## Rollback Procedure
|
||||
If issues arise, rollback with:
|
||||
\`\`\`bash
|
||||
git reset --hard HEAD~2 # Adjust commit count if needed
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
Document generated: ${new Date().toISOString()}
|
||||
`;
|
||||
|
||||
const checklistPath = path.join(projectRoot, 'POST_MIGRATION_CHECKLIST.md');
|
||||
fs.writeFileSync(checklistPath, checklist);
|
||||
log.success(`Created: POST_MIGRATION_CHECKLIST.md`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Main execution
|
||||
*/
|
||||
function main() {
|
||||
console.clear();
|
||||
console.log(`
|
||||
${colors.cyan}╔══════════════════════════════════════════════════════════╗
|
||||
║ POST-MIGRATION: Update References & Documentation ║
|
||||
║ Domain-Based API Structure (skydive/cms/herowars) ║
|
||||
╚══════════════════════════════════════════════════════════════════╝${colors.reset}
|
||||
`);
|
||||
|
||||
try {
|
||||
updateSwaggerYaml();
|
||||
updatePostmanFiles();
|
||||
findRemainingReferences();
|
||||
generateUpdateChecklist();
|
||||
|
||||
log.success(`\n✓ Post-migration updates completed!\n`);
|
||||
log.info(`Next steps:
|
||||
1. Review POST_MIGRATION_CHECKLIST.md
|
||||
2. Run the server: npm run local
|
||||
3. Test endpoints in Swagger UI
|
||||
4. Update frontend API calls
|
||||
5. Run tests and verify everything works
|
||||
\n`);
|
||||
} catch (error) {
|
||||
log.error(`Post-migration update failed: ${error.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
Reference in New Issue
Block a user