fix: disclose limitation about parameter schema reference

README.md

@@ -96,7 +96,7 @@ try {
 
 > **NOTE**: This feature is still WIP, and is until the final release of `3.0.0`.
 
-Conversion to version `3.x.x` from `2.x.x` has several assumptions that should be know before converting:
+Conversion to version `3.x.x` from `2.x.x` has several assumptions that should be known before converting:
 
 - The input must be valid AsyncAPI document.
 - External references are not resolved and converted, they remain untouched, even if they are incorrect.
@@ -164,6 +164,35 @@ Conversion to version `3.x.x` from `2.x.x` has several assumptions that should b
 ## Known missing features
 
 * When converting from 1.x to 2.x, Streaming APIs (those using `stream` instead of `topics` or `events`) are converted correctly but information about framing type and delimiter is missing until a [protocolInfo](https://github.com/asyncapi/extensions-catalog/issues/1) for that purpose is created.
+* When converting from 2.x to 3.x, and `parameter.schema` is defined with a reference, it will NOT look into the schema reference and include any relevant keywords for the v3 parameter. It will just create an empty parameter but leave the schema in the components section as is.
+  ```yaml
+  # 2.x.x
+  channels:
+    "{myParameter}":
+      parameters: 
+        myParameter: 
+          schema: 
+            $ref: "#/components/schemas/mySchema"
+  components: 
+    schemas:
+      mySchema:
+        enum: ["test"]
+        default: "test"
+        examples: ["test"]
+
+  # 3.0.0
+  channels:
+    "{myParameter}":
+      parameters: 
+        myParameter: {}
+
+  components: 
+    schemas:
+      mySchema:
+        enum: ["test"]
+        default: "test"
+        examples: ["test"]
+  ```
 
 ## Development
 

src/third-version.ts

@@ -391,6 +391,10 @@ function convertParameter(parameter: any): any {
     }
   }
 
+  if(parameter.schema?.$ref) {
+    console.error('Could not convert parameter object because the `.schema` property was a reference. This have to be changed manually if you want any of the properties included. The reference was ' + parameter.schema?.$ref);
+  }
+
   const enumValues = parameter.schema?.enum ?? null;
   const defaultValues = parameter.schema?.default ?? null;
   const description = parameter.description ?? parameter.schema?.description ?? null;

test/input/2.6.0/for-3.0.0-with-mixed-parameters.yml

@@ -19,7 +19,14 @@ channels:
         $ref: '#/components/parameters/location'
       mixed:
         $ref: '#/components/parameters/mixed'
+      schemaRef:
+        schema: 
+          $ref: '#/components/schemas/schemaParameter'
 components:
+  schemas: 
+    schemaParameter:
+      type: string
+      enum: ["test"]
   parameters:
     enum:
       schema:

test/output/3.0.0/from-2.6.0-with-mixed-parameters.yml

@@ -19,7 +19,12 @@ channels:
         $ref: '#/components/parameters/location'
       mixed:
         $ref: '#/components/parameters/mixed'
+      schemaRef: {}
 components:
+  schemas: 
+    schemaParameter:
+      type: string
+      enum: ["test"]
   parameters:
     enum:
       enum: ["test"]