Skip to content

Latest commit

 

History

History
115 lines (85 loc) · 4.58 KB

README.md

File metadata and controls

115 lines (85 loc) · 4.58 KB
Raw

VMware Cloud Director Rest OpenAPI definitions

OpenAPI definitions for vCloud's Rest API.

These can be used to generate libraries for interacting with vCloud from any mainstream programming langauge.

OpenAPI definitions are sometimes known by their previous name of Swagger specifications.

vCloud Director 10.2.2 Rest API

Other versions: see top level folder

In general, clients can be generated by running an openapi-generator command similar to:

openapi-generator generate -i 'https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/35.2.json' -g 'typescript-axios' -o 'src/vcloud-client'

Background

This is a repository of OpenAPI definitions for vCloud's Rest API. They are automatically generated from the public documentation to reduce human error, reduce human effort and to make it easy to stay up-to date.

vCloud Director has an official OpenAPI, but it contains little of the functionality of the Rest API.

Some of the documentation instructs the user to follow link attributes in the responses and not to create hrefs manually. This is incompatible with OpenAPI and contradicts other official documentation that lists out paths within the API. This definition uses predefined paths.

How the definitions are generated

VMware Cloud Director Rest API supports responses and requests as both JSON and XML. But only XML is officially documented by VMWare. JSON is better suited for OpenAPI and modern usage. The mapping from XML to JSON is predictable.

Types are documented by VMware in XSD (XML Schema Definition). XSD is a complicated format. It supports lots of concepts and it has multiple ways of expressing a single concept. There are edge cases where I've not yet incorporated an XSD concept.

Each API version has a zip file containing documentation about it on the vmware website. The zip file is downloaded and passed into a Rust program that extracts various information like responses, requests and paths. This program then generates a JSON OpenAPI definition.

If you find an issue, tell me about it using Github and I shall try and address it.

License

The transformer (code that does the converting of the published documentation to OpenAPI) is MIT Licensed.

I've assigned the copyright of the OpenAPI definitions to VMware as they are derived from their documentation.

Differences between versions

It may be useful to see what has changed between two versions. The key to getting a useful diff is to mask the version number in the content header. The following command lines are useful for seeing the differences between versions:

# If the repository is downloaded
diff -U20 --color=always \
  <(< 36.0.json sed -r 's/version=[0-9.]+/version=xx.x/') \
  <(< 36.3.json sed -r 's/version=[0-9.]+/version=xx.x/') \
  | less -R
# If the repository has not been downloaded
diff -U20 --color=always \
  <(
    curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.0.json \
    | sed -r 's/version=[0-9.]+/version=xx.x/'
  ) \
  <(
    curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.3.json \
    | sed -r 's/version=[0-9.]+/version=xx.x/'
  ) \
  | less -R

Known Issues

To fix the issue Unable to compile Java openapi client#3, run patch_java_openapi_client.sed as a temporary workaround

find <output directory> -regex '.*\(Type\|Value\|AllOf\|Test\)\.java' -exec grep -H '_type\|typeTest' {} \; -exec sed -ri -f patch_java_openapi_client.sed {} \;

Status

I used to work at a company that administered vCloud Director instances. As such, having a programmable way to manage them was useful to me.

My current company does not use vCloud Director. As such

  • I no longer use the vCloud Director API and can't verify these OpenAPI schemas against a real instance solving real problems
  • I'm not making changes except for adding newer versions and responding to GitHub issues