Generate a docs for properties that are a simple reference (#5129) (#5195)

For properties, generate an allOf schema with descriptions instead of references

Author: swallez

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -242,12 +242,28 @@ impl<'a> TypesAndComponents<'a> {
     }
 
     fn convert_property(&mut self, prop: &Property) -> anyhow::Result<ReferenceOr<Schema>> {
-        let mut result = self.convert_value_of(&prop.typ)?;
-        // TODO: how can we just wrap a reference so that we can add docs?
-        if let ReferenceOr::Item(ref mut schema) = &mut result {
-            self.fill_data_with_prop(&mut schema.schema_data, prop)?;
-        }
-        Ok(result)
+        let result = self.convert_value_of(&prop.typ)?;
+
+        // OpenAPI 3.0 doesn't allow adding summary and description to a reference. The recommended workaround
+        // is to use a schema with a single `allOf` - see https://github.com/OAI/OpenAPI-Specification/issues/1514
+        //
+        // OpenAPI 3.1 added summary and description for a `$ref` have been added to avoid the workaround
+        // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object
+
+        let mut schema = match result {
+            ReferenceOr::Item(schema) => schema,
+            reference @ ReferenceOr::Reference { reference: _ } => Schema {
+                schema_kind: SchemaKind::AllOf {
+                    all_of: vec![reference]
+                },
+                schema_data: Default::default(),
+            }
+        };
+
+        // Add docs & other properties
+        self.fill_data_with_prop(&mut schema.schema_data, prop)?;
+
+        Ok(ReferenceOr::Item(schema))
     }
 
     fn convert_properties<'b>(