openapiTS mutates the schema object

[duncanbeevers]

Description

openapiTS mutates the schema object. ($ref's mainly, it appears)

Reproduction

• Serialize schema with JSON.stringify()
• Pass schema with components and refs.
• Serialize schema with JSON.stringify() again
• Compare serializations to confirm transformation

openapiTS = await import('openapi-typescript').then((module) => module.default)

schema = {
  openapi: '3.0.2',
  info: {
    title: 'My Schema',
    description: 'This is a very fancy service.',
    version: '1.0',
    contact: {}
  },
  tags: [],
  paths: {
    '/{id}': {
      get: {
        parameters: [
          { name: 'id', in: 'path', schema: { $ref: '#/components/schemas/ObjectId' }, required: true }
        ],
        responses: {
          '204': {
            description: 'OK'
          }
        }
      }
    },
  },
  components: {
    schemas: {},
    links: {},
    callbacks: {}
  }
}

before = JSON.stringify(schema);
await openapiTS(schema)
after = JSON.stringify(schema);

same = before === after // false

Expected result

• API / type signatures accept readonly schemas
• Don't mutate the schema.

Checklist

• I’m willing to open a PR (see CONTRIBUTING.md)

[drwpow]

Ah you’re right. This isn’t good. I think it’s because in many cases, when loading from a file or URL, you get a fresh copy of the schema object, so the mutation wasn’t noticed. But in Node.js this shouldn’t happen.

This is a quick fix.

[duncanbeevers]

To be fair, the public API doesn't expect a readonly object, so it's kind of advertising that it could be dangerous. However, I don't think that's what anybody actually wants.

This issue happened when we started serializing the schema literal alongside the generated types so that we could export it as a TS as const.

This allows us to access enums from the schema with their literal types instead of the looser JSON-as-module types.

import schemaFromJson from 'schema.json';

const schema1 = schemaFromJson;

const schema2 = {
  components: {
    schemas: {
      AdventurerStatus: {
        type: 'string',
        enum: ['healthy', 'stunned', 'dead'],
      },
    },
  },
} as const;

type EnumFromJson = typeof schema1['components']['schemas']['AdventurerStatus']['enum'];
// string[]

type EnumFromConst = typeof schema2['components']['schemas']['AdventurerStatus']['enum'];
// ["healthy", "stunned", "dead"]