Issue when generating html docs from swagger file for vCenter 6.7

[alanrenouf]

Just tried the latest version of the openapi generator against 6.7 VC and it created me a swagger file but when i try and use it with an off the shelf doc generator (redoc) for a swagger file i get the following error

SyntaxError: Error resolving $ref pointer "/Users/renoufa/Dropbox%20(VMware)/Github/vmw-redoc/vcenter.json#/definitions/com.vmware.cis.task.status".
Token "com.vmware.cis.task.status" does not exist.
    at Pointer.resolve (/Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/pointer.js:87:17)
    at $Ref.resolve (/Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/ref.js:83:18)
    at $Refs._resolve (/Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/refs.js:155:15)
    at inventory$Ref (/Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/bundle.js:99:23)
    at /Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/bundle.js:74:11
    at Array.forEach (<anonymous>)
    at crawl (/Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/bundle.js:68:12)
    at /Users/renoufa/.npm/_npx/55113/lib/node_modules/redoc-cli/node_modules/json-schema-ref-parser/lib/bundle.js:77:11
    at Array.forEach (<anonymous>)

[kunal-pmj]

With all the fixes you should not be getting model with 'com.vmware.' prefixed to their names.
However, the error "Error resolving $ref pointer" is a bug when VC version is 6.7. Some of the model definitions in vcenter.json, like "vcenter.deployment.task", "vcenter.deployment.info" and "_vcenter.deployment.importhistory.info" refer to an undefined reference ""$ref": "#/definitions/cis.task.status" .

[alanrenouf]

So this is a bug we can fix? sorry was a little unclear as to what the resolution was here?

[sreeshas]

@kunal-pmj i think" com.vmware" prefix removal change caused this regression. There should not be any models with undefined reference. if you look here, https://10.160.107.125/apiexplorer/json/vcenter.json, we do find com.vmware.cis.task.status in definition section and everywhere it is being referred correctly.

Looks like "com.vmware" prefix removal change is missing a corner case.

[sreeshas]

It might also be a case where vcenter or appliance is referring to structure from cis package. If that is the case, we have to either pull the structure into vcenter or appliance or make a relative reference to structure in cis package.

[kunal-pmj]

Hi @sreeshas

The issue is reproducible in some Versions of VC.
The removal of "com.vmware." is ruled out because these changes are done only after the complete swagger is generated. I used following 67U1 VC: sc-rdops-vm17-dhcp-10-241.eng.vmware.com and the issue of missing "cis.task.status" is not reproducible here. However, Issue 20 reported by @kmruddy is reproducible.

This is a regression caused by this fix .

I am working on addressing it.

[kunal-pmj]

The issue is reproducible only on VC 6.7

It might also be a case where vcenter or appliance is referring to structure from cis package. If that is the case, we have to either pull the structure into vcenter or appliance or make a relative reference to structure in cis package.

You are right @sreeshas . The issue is reproducible only with the 6.7 vCenter. The structures defined in under cis are not available in vcenter or content. We need to get these structures from the other packages. I will create another branch locally and submit a review request with the approach.

thanks Kunal

[kunal-pmj]

Hi @sreeshas

Here are update on the issue. swagger editor, redoc etc report validation error because of missing model cis.task.progress and cis.task.status. I looked for their references in the cis.json from the same server but could not find it there as well. It seems the cis task apis where these models are actually used were introduced later and certainly not available in the cis.json from 6.7 version.

I am yet to check the the structures coming form the cis package for these models. Will try that and provide an update soon(early next week)

Thanks Kunal

[shashankkumar88]

Can anyone share the generated swagger file?

[kunal-pmj]

You can run the generator against your vcsa

[shashankkumar88]

You can run the generator against your vcsa

Thanks. However I don't have a vcsa. Is there a free version of vcsa available?

[kunal-pmj]

https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.install.doc/GUID-11468F6F-0D8C-41B1-82C9-29284630A4FF.html Follow the link.