Since vSphere 6.0, vSphere has been providing more and more REST based APIs.In vSphere 6.5, we introduced a new API Explorer and a number of new REST APIs, these also received significant updates in the vSphere 6.7 release. The vCenter API infrastructure provides json based metadata which describes APIs available in vCenter. This format is conceptually similar to the OpenAPI specification.
Today we are excited to announce a new, open-source project known as the VMware OpenAPI Generator.
The VMware OpenAPI Generator is a python-based utility which, when pointed at a vCenter server, can read all of the available API metadata and convert them into OpenAPI specifications. This allows you and 3rd party vendors to take advantage of all the available OpenAPI tooling to create additional artifacts such as documentation, code generators, and more.
Let’s take a look at how to use the VMware OpenAPI Generator.
VMware OpenAPI Generator
This new tool can be found on the VMware GitHub repository: VMware OpenAPI Generator
In order to make use of the tool, we’ll need to start by making the repository available on your local machine, by either clicking on the green “Clone or Download” button and selecting “Download Zip” or by simply running the following command:
|
1 |
git clone https://github.com/vmware/vmware-openapi-generator.git |
The other requirements are having Python and the vSphere Automation SDK for Python. Additional information about the installation process of both can be found at the following blog: Getting Started with the vSphere Automation SDK for Python
Once the above has been completed, we’re ready to produce our OpenAPI specifications based on a running vCenter server.
In this example, I’ll be using MacOS. I’ll open up a terminal session, change to the directory of our local copy of the “vmware-openapi-generator” repo, and use the following code:
|
1 |
python3 vmsgen.py -vc vcenter.fqdn -o /Path/for/exported/files |
Once complete, you should see the directory specified after the “o”(output) parameter has a number of JSON files containing each of the available REST services’ OpenAPI specifications.
Example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
{ "swagger": "2.0", "info": { "description": "VMware vCenter Server provides a centralized platform for managing your VMware vSphere environments", "title": "vcenter", "termsOfService": "http://swagger.io/terms/", "version": "2.0.0" }, "host": "<vcenter>", "basePath": "/rest", "tags": [], "schemes": [ "https", "http" ], "paths": { "/com/vmware/vcenter/inventory/datastore?~action=find": { "post": { "tags": [ "inventory_datastore" ], "summary": "Returns datastore information for the specified datastores. The key in the {@term result} {@term map} is the datastore identifier and the value in the {@term map} is the datastore information.", "parameters": [ { "in": "body", "name": "request_body", "required": true, "schema": { "$ref": "#/definitions/vcenter.inventory.datastore_find" } } ], "responses": { "200": { "description": "Datastore information for the specified datastores. The key in the {@term result} {@term map} is the datastore identifier and the value in the {@term map} is the datastore information.", "schema": { "$ref": "#/definitions/vcenter.inventory.datastore.find_result" } }, "404": { "description": "if no datastore can be found for one or more of the datastore identifiers in {@param.name datastores}", "schema": { "$ref": "#/definitions/vapi.std.errors.not_found_error" } } }, "consumes": [ "application/json" ], "operationId": "find" } }, |
Documentation Generator Example
OpenAPI specifications offers the ability to create any number of additional resources. One example of which is documentation. We can now take the newly generated specs for each of the vSphere API services and use a tool, like ReDoc, to then create a set of documentation. We can then combine it with other REST services to give us a consistent feel across all of our API documentation!
Let’s walk through a quick example of generating some documentation for the vCenter service using the ReDoc docker container:
|
1 2 |
docker pull redocly/redoc docker run -it --rm -p 80:80 -v $(PWD)/vcenter.json:/usr/share/nginx/html/vcenter.json -e SPEC_URL=vcenter.json redocly/redoc |
We can now open a browser and view our vCenter service documentation!
Summary
The vSphere REST APIs continue to get better with every release. We are also creating tools, such as the brand-new VMware OpenAPI Generator, which allows customers, partners and integrators to take advantage of all the tooling available in the OpenAPI ecosystem or custom projects which work with the OpenAPI format.
Download the VMware OpenAPI Generator today and let us know what you’re most excited about creating with these specs!
