.openapi() Breaking Change

[samchungy]

Resolves #303

.openapi() behaves a little differently now.

It now will attempt to store any previous openapi state and use it.

Why do we need this change?

1. Unintuitive Extension

   const FooSchema = z.string().openapi({ ref: 'string' });
   
   const BarSchema = z.object({
     a: FooSchema,
     b: FooSchema.openapi({ description: 'foo' }),
   });
   
   createSchema(BarSchema)

   This currently generates the following:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string' },
         b: { type: 'string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

   However, it's clear that the user simply wanted to reuse the FooSchema but describe it as something else later on.

   After:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string' },
         b: { '$ref': '#/components/schemas/string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

2. Broken .describe() behaviour on registered schemas

   	const FooSchema = z.string().openapi({ ref: 'string' });
   	
   	const BarSchema = z.object({
   	  a: FooSchema,
   	  b: FooSchema.describe('foo')
   	});
   	
   	createSchema(BarSchema)

   This scenario actually causes us to crash because it attempts to register the FooSchema twice with different objects because the .describe() triggers Schema "string" is already registered

   After:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string' },
         b: { '$ref': '#/components/schemas/string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

3. Unregistered Base Schemas. You would think that if you created a base schema, and used it in a schema with something like a description, we would register it? Right now? No.

   const FooSchema = z.string().openapi({ ref: 'string' });
   const BarSchema = z.object({
     a: FooSchema.describe('foo')
   });
   createSchema(BarSchema)

   {
     schema: {
       type: 'object',
       properties: { b: { type: 'string', description: 'foo' } },
       required: [ 'b' ]
     },
   }

   After:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

[samchungy]

TODO: Figure out how we're going to calculate previous state

[samchungy]

TODO: Add much more tests