feat: support for refs

[simonireilly]

Compeller needs to support refs, because refs are used heavily in OpenAPI specifications which become very large.

The specification itself will use refs to point at other declarations.

MVP

For an MVP, pointing at:

components.schema

Would be enough, in my opinion, to allow users to dry out their schema's.

Example

import { VersionSchema } from './schemas/version.schema';

export const OpenAPISpecification = {
  info: {
    title: 'New API generated with compeller',
    version: '1.0.0',
  },
  openapi: '3.1.0',
  paths: {
    'v1/version': {
      get: {
        responses: {
          '200': {
            description: 'Get the current API version',
            content: {
              'application/json': {
                schema: {
                  $ref: '#/components/schemas/Version',
                },
              },
            },
          },
        },
      },
    },
  },
  components: {
    schemas: {
      Version: {
        type: 'object',
        required: ['version'],
        additionalProperties: false,
        properties: {
          version: {
            type: 'string',
          },
        },
      } as const,
    },
  },
};

Research

This tool supports refs, and is suggested reading: https://github.com/Q42/openapi-typescript-validator

In principle we would be looking for the schema key to be ref and if so we would want to find the ref in the OpenAPI object, and use the ref type as the schema type.