/** Generate the canonical OAS3 document from actual DRF/Swagger definitions. */ import { readFileSync, writeFileSync } from 'node:fs'; import { resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; import converter from 'swagger2openapi'; import validator from 'oas-validator'; const base = fileURLToPath(new URL('../..', import.meta.url)); const input = process.argv.slice(2).find(argument => !argument.startsWith('--')) || resolve(base, 'tools/openapi/swagger.json'); const output = resolve(base, 'src/core/openapi.json'); const check = process.argv.includes('--check'); const swagger = JSON.parse(readFileSync(input, 'utf8')); const converted = await converter.convertObj(swagger, { patch: true, warnOnly: false }); const document = converted.openapi; const schemas = document.components.schemas; const clone = (value) => structuredClone(value); const ref = (name) => ({ $ref: `#/components/schemas/${name}` }); // Relative URLs work through the deployed frontend proxy and the backend origin. delete document.servers; document.info.description += '\n\nCanonical OpenAPI 3 contract: /openapi.json. Legacy Swagger 2 remains available at /?format=openapi.'; const variants = [ ['BudgetRegistry', 'budget_process_registry', 'budget_ubpandnubp', 'budget_registry_organization', 'BudgetRegistryRecord'], ['SmeSupport', 'government_support', 'fns_sme_support_recipients', 'sme_support_measure', 'SmeSupportRecord'], ['SroMembership', 'sro_membership', 'sro_membership_check', 'sro_membership', 'SroMembership'], ]; const extendedVariants = [ ['CheckoLeasing', 'leasing', 'checko_leasing', 'leasing_contract', 'CheckoLeasing'], ['CheckoMessage', 'company_messages', 'checko_messages', 'company_message', 'CheckoMessage'], ['CheckoLicense', 'company_licenses', 'checko_licenses', 'company_license', 'CheckoLicense'], ['FsspEnforcementProceeding', 'enforcement_proceedings', 'fssp_enforcement_proceedings', 'enforcement_proceeding', 'FsspEnforcementProceeding'], ['IntegratedStructure', 'integrated_structure_documents', 'integrated_structures', 'integrated_structure', 'IntegratedStructure'], ['FedresursCompanyProfile', 'fedresurs_company_profile', 'fedresurs_company_profile', 'company_profile', 'FedresursCompanyProfile'], ]; const requiredRecordFields = [ 'uid', 'source_group', 'source', 'record_type', 'external_id', 'title', 'status', 'created_at', 'updated_at', 'organization', 'payload', ]; const listOperation = document.paths['/api/v2/organization-source-records/']?.get; if (!listOperation) throw new Error('Source records list operation missing'); const groupParameter = listOperation.parameters.find((parameter) => parameter.name === 'source_group'); const legacyGroups = groupParameter.schema.enum.filter((group) => ![...variants, ...extendedVariants].some((variant) => variant[1] === group)); schemas.PublishedSourceRecordOrganization = clone(schemas.OrganizationSourceRecordOrganization); schemas.PublishedSourceRecordOrganization.required = ['uid', 'name', 'inn', 'ogrn', 'okpo']; for (const [name, property] of Object.entries(schemas.PublishedSourceRecordOrganization.properties)) { if (name !== 'uid' && name !== 'name') property.nullable = true; } schemas.SroSourceRecordOrganization = clone(schemas.PublishedSourceRecordOrganization); schemas.SroSourceRecordOrganization.required.push('full_name'); for (const field of schemas.SroSourceRecordOrganization.required) { delete schemas.SroSourceRecordOrganization.properties[field].nullable; } schemas.FsspSourceRecordOrganization = clone(schemas.PublishedSourceRecordOrganization); for (const field of ['name', 'inn', 'ogrn', 'okpo']) { delete schemas.FsspSourceRecordOrganization.properties[field].nullable; schemas.FsspSourceRecordOrganization.properties[field].minLength = 1; } for (const [field, length] of [['inn', 10], ['ogrn', 13], ['okpo', 8]]) { schemas.FsspSourceRecordOrganization.properties[field].pattern = `^[0-9]{${length}}$`; } for (const [schemaName, kind] of [ ['OrganizationSourceRecordList', 'List'], ['OrganizationSourceRecord', 'Detail'], ]) { const common = clone(schemas[schemaName]); if (!common?.properties?.payload) throw new Error(`${schemaName} has no payload`); const legacyName = `Legacy${schemaName}`; schemas[legacyName] = clone(common); schemas[legacyName].properties.source_group = { type: 'string', enum: legacyGroups }; schemas[legacyName].required = [...new Set([...(common.required || []), 'source_group'])]; const oneOf = [ref(legacyName)]; const mapping = Object.fromEntries(legacyGroups.map((group) => [group, ref(legacyName).$ref])); for (const [prefix, group, source, recordType, payloadPrefix] of variants) { const payloadName = `${payloadPrefix}${kind}Payload`; if (!schemas[payloadName]) throw new Error(`Named payload missing: ${payloadName}`); const variantName = `${prefix}Record${kind}`; const schema = clone(common); schema.required = [...new Set([...(schema.required || []), ...requiredRecordFields])]; schema.properties.source_group = { type: 'string', enum: [group] }; schema.properties.source = { type: 'string', enum: [source] }; schema.properties.record_type = { type: 'string', enum: [recordType] }; schema.properties.status = { type: 'string', enum: { budget_process_registry: ['active', 'inactive', 'special', 'unknown'], government_support: ['published'], sro_membership: ['active', 'excluded'], }[group] }; schema.properties.payload = ref(payloadName); schema.properties.organization = ref(group === 'sro_membership' ? 'SroSourceRecordOrganization' : 'PublishedSourceRecordOrganization'); schemas[variantName] = schema; oneOf.push(ref(variantName)); mapping[group] = ref(variantName).$ref; } schemas[schemaName] = { oneOf, discriminator: { propertyName: 'source_group', mapping }, description: 'Published source record. source_group selects the variant; record_type and source are fixed within each registry variant.', }; } // Keep the generated enum name consumed by existing media/sanctions hooks, and // describe arbitrary validated comma-separated combinations without enumerating // factorially many permutations or pretending ordering is an array on the wire. const ordering = listOperation.parameters.find((parameter) => parameter.name === 'ordering'); const values = ordering.schema.enum.filter((value) => !value.includes(',')); const escapedValues = values.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')); schemas.V2OrganizationSourceRecordsListOrdering = { type: 'string', enum: values }; schemas.SourceRecordOrderingSequence = { type: 'string', pattern: `^(?:${escapedValues.join('|')})(?:,(?:${escapedValues.join('|')}))+$`, description: 'Two or more allowlisted ordering fields, separated by commas without spaces.', }; ordering.schema = { anyOf: [ref('V2OrganizationSourceRecordsListOrdering'), ref('SourceRecordOrderingSequence')], }; // drf-yasg's read-only flags do not express response requiredness consistently. for (const name of ['OrganizationSourceRecordListResponse', 'SourceRecordMeta', 'SourceRecordPagination']) { schemas[name].required = Object.keys(schemas[name].properties); } schemas.OrganizationSourceRecordListResponse.properties.errors = { type: 'object', nullable: true, enum: [null] }; // The two richer source payloads have stable public DTOs in addition to the // generic DRF JSONField. Keep these schemas beside the canonical converter so // both backend /openapi.json and the frontend client come from one contract. const extensions = JSON.parse(readFileSync(resolve(base, 'tools/openapi/source-record-extensions.json'), 'utf8')); for (const [name, schema] of Object.entries(extensions)) { if (schemas[name]) throw new Error(`Duplicate source schema: ${name}`); schemas[name] = schema; } for (const [prefix, group, source, recordType, payloadPrefix] of extendedVariants) { for (const [schemaName, kind] of [ ['OrganizationSourceRecordList', 'List'], ['OrganizationSourceRecord', 'Detail'], ]) { const variantName = `${prefix}Record${kind}`; const payloadName = `${payloadPrefix}${kind}Payload`; if (!schemas[payloadName]) throw new Error(`Named payload missing: ${payloadName}`); const schema = clone(schemas[`Legacy${schemaName}`]); schema.required = [...new Set([...(schema.required || []), ...requiredRecordFields])]; schema.properties.source_group = { type: 'string', enum: [group] }; schema.properties.source = { type: 'string', enum: [source] }; schema.properties.record_type = { type: 'string', enum: [recordType] }; schema.properties.status = { type: 'string' }; schema.properties.payload = ref(payloadName); schema.properties.organization = ref('SroSourceRecordOrganization'); if (['leasing', 'company_messages', 'company_licenses'].includes(group)) { schema.properties.organization = ref('FsspSourceRecordOrganization'); } if (group === 'enforcement_proceedings') { schema.required = [...new Set([...schema.required, 'extension_uid', 'record_date', 'amount', 'url', 'legacy_model', 'legacy_pk', 'load_batch', 'financial_lines'])]; schema.properties.status = { type: 'string', enum: ['unknown', 'ended', 'terminated'] }; schema.properties.amount = { type: 'string', pattern: '^-?[0-9]+\\.[0-9]{2}$', nullable: true }; schema.properties.record_date = { type: 'string', format: 'date', nullable: true }; for (const field of ['legacy_model', 'legacy_pk']) schema.properties[field] = { type: 'string', enum: [''] }; schema.properties.financial_lines = { type: 'array', items: {}, maxItems: 0 }; schema.properties.organization = ref('FsspSourceRecordOrganization'); } schemas[variantName] = schema; schemas[schemaName].oneOf.push(ref(variantName)); schemas[schemaName].discriminator.mapping[group] = ref(variantName).$ref; } } const attachmentPath = document.paths['/api/v2/organization-source-records/{uid}/documents/{document_id}/attachment/']; if (!attachmentPath?.get) throw new Error('Integrated attachment endpoint missing'); attachmentPath.get.responses['200'] = { description: 'Immutable RTF attachment', content: { 'application/rtf': { schema: { type: 'string', format: 'binary' } } }, }; attachmentPath.get.responses['409'] = { description: 'attachment_unavailable', content: { 'application/json': { schema: ref('AttachmentUnavailableError') } }, }; document.paths['/api/v1/parsers/upload/fedresurs_company_profile/'] = { post: { operationId: 'api_v1_parsers_upload_fedresurs_company_profile_create', summary: 'Fedresurs public UI does not accept file uploads', description: 'Use the Fedresurs refresh endpoint instead of multipart upload.', responses: { '405': { description: 'upload_not_supported', content: { 'application/json': { schema: ref('FedresursUploadNotSupportedError') } }, }, }, tags: ['Parser Management'], }, }; schemas.FedresursUploadNotSupportedError = { type: 'object', required: ['success', 'errors'], properties: { success: { type: 'boolean', enum: [false] }, errors: { type: 'array', items: { type: 'object', required: ['code', 'message'], properties: { code: { type: 'string', enum: ['upload_not_supported'] }, message: { type: 'string' }, }, }, }, }, }; // Swagger's pagination inspector emits required:[] for legacy envelopes. Omitting // this empty constraint preserves its meaning and is valid in OpenAPI 3.0. function removeEmptyRequired(value) { if (!value || typeof value !== 'object') return; if (Array.isArray(value.required) && value.required.length === 0) delete value.required; for (const child of Object.values(value)) removeEmptyRequired(child); } removeEmptyRequired(document); const encoded = JSON.stringify(document, null, 2) + '\n'; await validator.validate(JSON.parse(encoded), { lint: false, validateSchema: true }); if (check) { if (readFileSync(output, 'utf8') !== encoded) throw new Error('Canonical openapi.json is stale; regenerate it from the current backend'); console.log('Canonical OpenAPI matches runtime schema'); } else { writeFileSync(output, encoded); console.log(`Generated ${Object.keys(document.paths).length} paths, ${Object.keys(schemas).length} schemas`); }