{"id":17997755,"url":"https://github.com/ccouzens/vcloud-rest-openapi","last_synced_at":"2025-03-26T04:31:32.396Z","repository":{"id":45786255,"uuid":"268911172","full_name":"ccouzens/vcloud-rest-openapi","owner":"ccouzens","description":"OpenAPI definitions for vCloud Director's Rest API","archived":false,"fork":false,"pushed_at":"2024-06-25T05:38:04.000Z","size":16609,"stargazers_count":12,"open_issues_count":2,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-18T07:49:22.861Z","etag":null,"topics":["openapi","openapi-definitions","vcloud-director"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccouzens.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-02T21:20:32.000Z","updated_at":"2024-06-25T05:38:08.000Z","dependencies_parsed_at":"2024-10-29T22:12:40.405Z","dependency_job_id":null,"html_url":"https://github.com/ccouzens/vcloud-rest-openapi","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccouzens%2Fvcloud-rest-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccouzens%2Fvcloud-rest-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccouzens%2Fvcloud-rest-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccouzens%2Fvcloud-rest-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccouzens","download_url":"https://codeload.github.com/ccouzens/vcloud-rest-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245589265,"owners_count":20640254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","openapi-definitions","vcloud-director"],"created_at":"2024-10-29T21:21:16.858Z","updated_at":"2025-03-26T04:31:30.380Z","avatar_url":"https://github.com/ccouzens.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VMware Cloud Director Rest OpenAPI definitions\n\nOpenAPI definitions for vCloud's Rest API.\n\nThese can be used to generate libraries for interacting with vCloud from any\nmainstream programming langauge.\n\nOpenAPI definitions are sometimes known by their previous name of Swagger\nspecifications.\n\n[vCloud Director 10.2.2 Rest API](./35.2.json)\n\nOther versions: see top level folder\n\nIn general, clients can be generated by running an\n[openapi-generator](https://github.com/OpenAPITools/openapi-generator) command\nsimilar to:\n\n```bash\nopenapi-generator generate -i 'https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/35.2.json' -g 'typescript-axios' -o 'src/vcloud-client'\n```\n\n## Background\n\nThis is a repository of OpenAPI definitions for vCloud's Rest API. They are\nautomatically generated from the public documentation to reduce human error,\nreduce human effort and to make it easy to stay up-to date.\n\nvCloud Director has an\n[official](https://vdc-download.vmware.com/vmwb-repository/dcr-public/772aa4c5-7e61-4d80-8432-b8e0d821c969/2747ec83-6aef-4560-b1d1-55ed9adc4e73/vcd-openapi-docs.html)\n[OpenAPI](https://github.com/vmware/vcd-api-schemas/blob/master/schemas/openapi/src/main/resources/schemas/vcloud-openapi-schemas.yaml),\nbut it contains little of the functionality of the\n[Rest API](https://developer.broadcom.com/xapis/vmware-cloud-director-api/38.1/).\n\n[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)\ninstructs the user to follow `link` attributes in the responses and not to\ncreate `href`s manually. This is incompatible with OpenAPI and contradicts other\nofficial documentation that lists out paths within the API. This definition uses\npredefined paths.\n\n## How the definitions are generated\n\nVMware Cloud Director Rest API supports responses and requests as both JSON and\nXML. But only XML is officially documented by VMWare. JSON is better suited for\nOpenAPI and modern usage. The mapping from XML to JSON is predictable.\n\nTypes are documented by VMware in XSD (XML Schema Definition). XSD is a\ncomplicated format. It supports lots of concepts and it has multiple ways of\nexpressing a single concept. There are edge cases where I've not yet\nincorporated an XSD concept.\n\nEach API version has a zip file containing documentation about it on the vmware\nwebsite. The zip file is downloaded and passed into a Rust program that extracts\nvarious information like responses, requests and paths. This program then\ngenerates a JSON OpenAPI definition.\n\nIf you find an issue, tell me about it using\n[Github](https://github.com/ccouzens/vcloud-rest-openapi/issues) and I shall try\nand address it.\n\n## License\n\nThe transformer (code that does the converting of the published documentation to\nOpenAPI) is MIT Licensed.\n\nI've assigned the copyright of the OpenAPI definitions to VMware as they are\nderived from their documentation.\n\n## Differences between versions\n\nIt may be useful to see what has changed between two versions. The key to\ngetting a useful diff is to mask the version number in the content header. The\nfollowing command lines are useful for seeing the differences between versions:\n\n```bash\n# If the repository is downloaded\ndiff -U20 --color=always \\\n  \u003c(\u003c 36.0.json sed -r 's/version=[0-9.]+/version=xx.x/') \\\n  \u003c(\u003c 36.3.json sed -r 's/version=[0-9.]+/version=xx.x/') \\\n  | less -R\n```\n\n```bash\n# If the repository has not been downloaded\ndiff -U20 --color=always \\\n  \u003c(\n    curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.0.json \\\n    | sed -r 's/version=[0-9.]+/version=xx.x/'\n  ) \\\n  \u003c(\n    curl -s https://raw.githubusercontent.com/ccouzens/vcloud-rest-openapi/main/36.3.json \\\n    | sed -r 's/version=[0-9.]+/version=xx.x/'\n  ) \\\n  | less -R\n```\n\n## Known Issues\n\n[Unable to compile Java openapi client#3](https://github.com/ccouzens/vcloud-rest-openapi/issues/3) \n\nThe temporary workaround:\n\n1. 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\n\n\n2. Clean up the codegenerated client \u003coutput directory\u003e:\n```bash\n  rm -rf \u003coutput directory\u003e\n```\n\n3. Run the script from the root project directory:\n```bash\nfind ./\u003coutput directory\u003e -regex '.*\\(Type\\|Value\\)\\.java' -exec grep -H 'String JSON_PROPERTY_TYPE = \"_type\"' {} \\; -exec sed -ri -f ./fix-vcd-type-discriminator_01.sed {} \\; \u0026\u0026 find ./\u003coutput directory\u003e/ -regex '.*\\(Type\\|Value\\)\\.java' -exec grep -H 'extends .*\\(Type\\|Value\\)' {} \\; -exec sed -ri -f ./fix-vcd-type-discriminator_02.sed {} \\;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccouzens%2Fvcloud-rest-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccouzens%2Fvcloud-rest-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccouzens%2Fvcloud-rest-openapi/lists"}