Expand or wrap refs to preserve descriptions

[gainsley]

We customize the go-swagger generator to overcome the issue noted here: OAI/OpenAPI-Specification#556.

The issue is that when generating a swagger definition from code, the description comment for a field is ignored if the field is an object. The description is instead taken from the description of the object.

For example, for a struct like:

// GPS Location
type Loc struct {
    ...
}

// Cloudlet
type Cloudlet struct {
    // Location of the Cloudlet site
    Location Loc

The generated swagger description of the Cloudlet.Location field would end up being "GPS Location" instead of "Location of the Cloudlet site". Beside the description now lacking proper context, this has obvious drawbacks if you have more than one instance of the same object in a struct.

The OpenAPI issue only provides a work-around, which is in the swagger to wrap a #ref with an "allOf" closure, which allows for the field description to be used. The other work-around is to flatten the object definition, putting all fields inline, rather than using a reference.

In this change, we do both. For enums, we use the "allOf" wrapper. For structs, we flatten, because we also want to deal with another issue that swagger doesn't support. This issue is that for multiple APIs (create/update/delete) that use the same object (Cloudlet), but have different allowed fields (for example UpdateCloudlet does not allow the PlatformType to be specified), we want to be able to tailor the allowed fields per API. This can't be done when using a #ref reference, since the specifiable fields then come from the Cloudlet struct definition, which is shared by all referring APIs.

So this change causes objects to be flattened, and enums to be wrapped in an extra "allOf" closure, in order to preserve field descriptions, and allow us to tailor which fields are specified per API. The per-API field manipulation is done as a post-processing step, not part of this repo.

[ashxjain]

Looks good. Do you think we should add a unit-test for this change as part of schema_test.go?

[gainsley]

That's a great suggestion Ashish, I hadn't though of checking and updating the unit tests. Unfortunately, it seems their unit tests are in a sorry state. There are currently two tests that stall and panic out after 10 minutes. Maybe if there are some upstream fixes to the unit tests we can look into this again later.