|
1 | 1 | # VMware Cloud Director Rest OpenAPI definitions |
2 | 2 |
|
3 | | -OpenAPI definitions for vCloud's Rest API. |
4 | | - |
5 | | -These can be used to generate libraries for interacting with vCloud from any |
6 | | -mainstream programming langauge. |
7 | | - |
8 | | -OpenAPI definitions are sometimes known by their previous name of Swagger |
9 | | -specifications. |
10 | | - |
11 | | -[vCloud Director 10.2.2 Rest API](./35.2.json) |
12 | | - |
13 | | -Other versions: see top level folder |
14 | | - |
15 | | -In general, clients can be generated by running an |
16 | | -[openapi-generator](https://github.com/OpenAPITools/openapi-generator) command |
17 | | -similar to: |
18 | | - |
19 | | -```bash |
20 | | -openapi-generator generate -i 'https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/35.2.json' -g 'typescript-axios' -o 'src/vcloud-client' |
21 | | -``` |
22 | | - |
23 | | -## Background |
24 | | - |
25 | | -This is a repository of OpenAPI definitions for vCloud's Rest API. They are |
26 | | -automatically generated from the public documentation to reduce human error, |
27 | | -reduce human effort and to make it easy to stay up-to date. |
28 | | - |
29 | | -vCloud Director has an |
30 | | -[official](https://vdc-download.vmware.com/vmwb-repository/dcr-public/772aa4c5-7e61-4d80-8432-b8e0d821c969/2747ec83-6aef-4560-b1d1-55ed9adc4e73/vcd-openapi-docs.html) |
31 | | -[OpenAPI](https://github.com/vmware/vcd-api-schemas/blob/master/schemas/openapi/src/main/resources/schemas/vcloud-openapi-schemas.yaml), |
32 | | -but it contains little of the functionality of the |
33 | | -[Rest API](https://developer.broadcom.com/xapis/vmware-cloud-director-api/38.1/). |
34 | | - |
35 | | -[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) |
36 | | -instructs the user to follow `link` attributes in the responses and not to |
37 | | -create `href`s manually. This is incompatible with OpenAPI and contradicts other |
38 | | -official documentation that lists out paths within the API. This definition uses |
39 | | -predefined paths. |
40 | | - |
41 | | -## How the definitions are generated |
42 | | - |
43 | | -VMware Cloud Director Rest API supports responses and requests as both JSON and |
44 | | -XML. But only XML is officially documented by VMWare. JSON is better suited for |
45 | | -OpenAPI and modern usage. The mapping from XML to JSON is predictable. |
46 | | - |
47 | | -Types are documented by VMware in XSD (XML Schema Definition). XSD is a |
48 | | -complicated format. It supports lots of concepts and it has multiple ways of |
49 | | -expressing a single concept. There are edge cases where I've not yet |
50 | | -incorporated an XSD concept. |
51 | | - |
52 | | -Each API version has a zip file containing documentation about it on the vmware |
53 | | -website. The zip file is downloaded and passed into a Rust program that extracts |
54 | | -various information like responses, requests and paths. This program then |
55 | | -generates a JSON OpenAPI definition. |
56 | | - |
57 | | -If you find an issue, tell me about it using |
58 | | -[Github](https://github.com/ccouzens/vcloud-rest-openapi/issues) and I shall try |
59 | | -and address it. |
60 | | - |
61 | | -## License |
62 | | - |
63 | | -The transformer (code that does the converting of the published documentation to |
64 | | -OpenAPI) is MIT Licensed. |
65 | | - |
66 | | -I've assigned the copyright of the OpenAPI definitions to VMware as they are |
67 | | -derived from their documentation. |
68 | | - |
69 | | -## Differences between versions |
70 | | - |
71 | | -It may be useful to see what has changed between two versions. The key to |
72 | | -getting a useful diff is to mask the version number in the content header. The |
73 | | -following command lines are useful for seeing the differences between versions: |
74 | | - |
75 | | -```bash |
76 | | -# If the repository is downloaded |
77 | | -diff -U20 --color=always \ |
78 | | - <(< 36.0.json sed -r 's/version=[0-9.]+/version=xx.x/') \ |
79 | | - <(< 36.3.json sed -r 's/version=[0-9.]+/version=xx.x/') \ |
80 | | - | less -R |
81 | | -``` |
82 | | - |
83 | | -```bash |
84 | | -# If the repository has not been downloaded |
85 | | -diff -U20 --color=always \ |
86 | | - <( |
87 | | - curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.0.json \ |
88 | | - | sed -r 's/version=[0-9.]+/version=xx.x/' |
89 | | - ) \ |
90 | | - <( |
91 | | - curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.3.json \ |
92 | | - | sed -r 's/version=[0-9.]+/version=xx.x/' |
93 | | - ) \ |
94 | | - | less -R |
95 | | -``` |
96 | | - |
97 | | -## Known Issues |
98 | | - |
99 | | -[Unable to compile Java openapi client#3](https://github.com/ccouzens/vcloud-rest-openapi/issues/3) |
100 | | - |
101 | | -The temporary workaround: |
102 | | - |
103 | | -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 |
104 | | - |
105 | | - |
106 | | -2. Clean up the codegenerated client <output directory>: |
107 | | -```bash |
108 | | - rm -rf <output directory> |
109 | | -``` |
110 | | - |
111 | | -3. Run the script from the root project directory: |
112 | | -```bash |
113 | | -find ./<output directory> -regex '.*\(Type\|Value\)\.java' -exec grep -H 'String JSON_PROPERTY_TYPE = "_type"' {} \; -exec sed -ri -f ./fix-vcd-type-discriminator_01.sed {} \; && find ./<output directory>/ -regex '.*\(Type\|Value\)\.java' -exec grep -H 'extends .*\(Type\|Value\)' {} \; -exec sed -ri -f ./fix-vcd-type-discriminator_02.sed {} \; |
114 | | -``` |
| 3 | +This project is archived. Please switch to [Gankarloo's fork](https://github.com/Gankarloo/vcloud-rest-openapi). |
0 commit comments