Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ccouzens/vcloud-rest-openapi
OpenAPI definitions for vCloud Director's Rest API
https://github.com/ccouzens/vcloud-rest-openapi
openapi openapi-definitions vcloud-director
Last synced: 17 days ago
JSON representation
OpenAPI definitions for vCloud Director's Rest API
- Host: GitHub
- URL: https://github.com/ccouzens/vcloud-rest-openapi
- Owner: ccouzens
- Created: 2020-06-02T21:20:32.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-06-25T05:38:04.000Z (5 months ago)
- Last Synced: 2024-06-25T06:45:52.694Z (5 months ago)
- Topics: openapi, openapi-definitions, vcloud-director
- Language: Rust
- Homepage:
- Size: 15.8 MB
- Stars: 12
- Watchers: 5
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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](./35.2.json)
Other versions: see top level folder
In general, clients can be generated by running an
[openapi-generator](https://github.com/OpenAPITools/openapi-generator) command
similar to:
```bash
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](https://vdc-download.vmware.com/vmwb-repository/dcr-public/772aa4c5-7e61-4d80-8432-b8e0d821c969/2747ec83-6aef-4560-b1d1-55ed9adc4e73/vcd-openapi-docs.html)
[OpenAPI](https://github.com/vmware/vcd-api-schemas/blob/master/schemas/openapi/src/main/resources/schemas/vcloud-openapi-schemas.yaml),
but it contains little of the functionality of the
[Rest API](https://developer.broadcom.com/xapis/vmware-cloud-director-api/38.1/).
[Some of the documentation](https://vdc-download.vmware.com/vmwb-repository/dcr-public/1b6cf07d-adb3-4dba-8c47-9c1c92b04857/241956dd-e128-4fcc-8131-bf66e1edd895/vcloud_sp_api_guide_30_0.pdf)
instructs the user to follow `link` attributes in the responses and not to
create `href`s 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](https://github.com/ccouzens/vcloud-rest-openapi/issues) 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:
```bash
# 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
```
```bash
# 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
[Unable to compile Java openapi client#3](https://github.com/ccouzens/vcloud-rest-openapi/issues/3)
The temporary workaround:
1. Copy patch scripts [fix-vcd-type-discriminator_01.sed](fix-vcd-type-discriminator_01.sed) and [fix-vcd-type-discriminator_02.sed](fix-vcd-type-discriminator_02.sed) to the root project directory
2. Clean up the codegenerated client :
```bash
rm -rf
```
3. Run the script from the root project directory:
```bash
find ./ -regex '.*\(Type\|Value\)\.java' -exec grep -H 'String JSON_PROPERTY_TYPE = "_type"' {} \; -exec sed -ri -f ./fix-vcd-type-discriminator_01.sed {} \; && find .// -regex '.*\(Type\|Value\)\.java' -exec grep -H 'extends .*\(Type\|Value\)' {} \; -exec sed -ri -f ./fix-vcd-type-discriminator_02.sed {} \;
```