Swagger: reuse schemas across exposed types

Let’s consider swagger.json for Bitbucket 8.5, particularly RestProject and RestRepository types (or schemas) from “schemas” section.

RestRepository has property project of type object with some properties. As you can easily these properties are exactly ones from RestProject type. The schema for RestProject type is just “inllined” into that particular property. I see 46 usages of "example": "My Cool Project" in this file and all of them belong to the logically same type - RestProject. That explains why the file is so huge - 48363 lines.

The same problem exists for other types and enums - many of them are duplicated. So the question is - why not to use the $ref syntax to reuse existing type and save type identity across file?

 "type": { "$ref": "#/components/schemas/<SOMETYPE>" }

This is essentially important for autogenerated strong-typed REST clients, for example those ones built by NSwag for .NET. Generated code contains:

• 45 classes for project “entity” - from Project to Project45
• 19 classes for repository “entity” - from Repository to Repository19
• 7 classes for FromRef
• and so on…

In addition to looking ridiculous, this complicates customization of the serialization settings, since they need to be applied for each type separately.