Cloudstack API documentation is woefully out of date

[ilsaloving-gander]

problem

I was having trouble getting the cloudstack terraform provider to work, and I ended up tracking the problem all the way back to the API. Are the API docs edited by hand? Because they are very out of date compared to the actual API code.

This has caused a cascading set of problems with everything depending on the API, including the Cloudstack terraform provider, and the Cloudstack go library that that provider depends on.

versions

4.21

The steps to reproduce the bug

n/a

What to do about it?

Where can we find up to date documentation?

[shwstppr]

@ilsaloving-gander it would help if you can elaborate and pin point your issue. CloudStack API documentation is auto generated based on annotations in the java code

[DaanHoogland]

@ilsaloving-gander , please look at https://cloudstack.apache.org/api/ all api docs for releases since the project was donated to apache are there. This of course can be improved, so as @shwstppr said, please elaborate on what you are missing.

[ilsaloving-gander]

The ListTrafficTypes response structure is completely wrong. I haven't gone through the rest of the api but seeing how this function is so completely wrong, it makes me think something is wrong with the documentation creation. I checked the java file and it seems like it should be generating fine, but I haven't done java dev in many years so I may be wrong.

I tried to create the docs myself using the wiki instructions (using mvn -Pdeveloper -Dnoredist -DskipTests clean install) , but all I get is endless compilation errors, so I question whether the documentation is even being generated correctly.

So far:

• aspectjweaver has a zip file problem that is fixed in 1.8.14
• I had to disable tests because one of them was failing to mock something up
• The final one I'm stuck on is:

[ERROR] Failed to execute goal on project cloud-plugin-hypervisor-kvm: Could not collect dependencies for project org.apache.cloudstack:cloud-plugin-hypervisor-kvm:jar:4.21.0.0
[ERROR] Failed to read artifact descriptor for org.libvirt:libvirt:jar:0.5.3
[ERROR] 	Caused by: The following artifacts could not be resolved: org.libvirt:libvirt:pom:0.5.3 (absent): Could not transfer artifact org.libvirt:libvirt:pom:0.5.3 from/to libvirt.org.maven2 (https://libvirt.org/maven2/): (certificate_expired) PKIX path validation failed: java.security.cert.CertPathValidatorException: validity check failed

[DaanHoogland]

The libvirt maven package has caused problems indeed lately. I noticed that as well. In general the compilation passes without problem. Github actions are running on all PRs.

This is my result for that API. Can you pin point what part of it is incorrect?

 🐱 > list traffictypes physicalnetworkid=4cd6c8c9-3cce-4e9f-bcad-88417e3bb198 
{
  "count": 2,
  "traffictype": [
    {
      "id": "20ce9737-5f33-4f35-ace1-968c3b464e5b",
      "kvmnetworklabel": "cloudbr1",
      "physicalnetworkid": "4cd6c8c9-3cce-4e9f-bcad-88417e3bb198",
      "traffictype": "Guest",
      "vmwarenetworklabel": "vSwitch1,,vmwaresvs",
      "xennetworklabel": "Network1"
    },
    {
      "id": "656c0575-bc81-4cb0-bf09-6e4ef5720086",
      "kvmnetworklabel": "cloudbr1",
      "physicalnetworkid": "4cd6c8c9-3cce-4e9f-bcad-88417e3bb198",
      "traffictype": "Public",
      "vmwarenetworklabel": "vSwitch1,,vmwaresvs",
      "xennetworklabel": "Network1"
    }
  ]
}

[ilsaloving-gander]

This is what the docs say the response should be (https://cloudstack.apache.org/api/apidocs-4.21/apis/listTrafficTypes.html)

id - uuid of the network provider
canenableindividualservice - true if individual services can be enabled/disabled
destinationphysicalnetworkid - the destination physical network
name - the provider name
physicalnetworkid - the physical network this belongs to
servicelist - services for this provider
state - state of the network provider

It looks like a the response documentation is for a completely different API. The only field in the docs that actually corresponds to the actual API output is physicalnetworkid.

[weizhouapache]

@ilsaloving-gander
Pearl has created a PR to fix it: #11875

if you find more issues, please create a github issue with some details, thanks

[weizhouapache]

you can find the correct response in
https://github.com/apache/cloudstack/blob/main/api/src/main/java/org/apache/cloudstack/api/response/TrafficTypeResponse.java