OpenAPI specific is very incomplete

[remy.greinhofer (Rémy Greinhofer)]

We are trying to use the OpenAPI specification you provide to generate Go and Python SDKs, but we are encountering various problems.

The first one is that a lot of definitions are incomplete and simply contain this message: “NOTE: This definition is not complete. We will be adding more detail in future releases of Octopus.” An example of that would be the " Channels" resource.

Another problem we are facing, is that when there are definitions they are incorrect. As an example I chose the “Lifecycles” resource, which expected a “Unit” as integer:
RetentionPeriod{
Unit integer($int32)
readOnly: true
Enum:
[ Days, Items ]

But in reality what is retrieved is a string:
“ReleaseRetentionPolicy”: {
“Unit”: “Days”,
“QuantityToKeep”: 15,
“ShouldKeepForever”: false
},
“TentacleRetentionPolicy”: {
“Unit”: “Items”,
“QuantityToKeep”: 5,
“ShouldKeepForever”: false
},

As a result, we cannot perform any schema validation.

Is there any plan to update this document to make is useful?

Thanks a lot in advance for your help.

[anon61686641]

Hi Remy
Thanks for getting in touch.
Due to the nature of the API layer in Octopus Deploy the swagger documention is largely generated by custom code in our web layer. As such there may be some limitations which we deliberately call out.

It looks like there was a bug with the enums (like the Unit you identified on the RetentionPeriod) . I have already put in a fix for this and it should go out in the next release in the next few days. This will likely be 2019.4.0.

What it the problem you have identified with the Channels resource?
Rob

[remy.greinhofer (Rémy Greinhofer)]

@anon61686641

Channels

Thanks a lot for your quick reply.

We are using LTS, so I’ll have to wait for the next LTS version to get the fix.

No direct problem with Channels resource, it is just that a lot of resources don’t have a full documentation nor a clear example.