API Documentation for VMware Products with Platypus

I consider APIs as the Graal for building, maintaining, operating and monitoring your applications and infrastructures. However, finding API documentation can be difficult, especially if you don’t know where to look: this is where Platypus intervenes! :)

A few days ago, I was procrastinating on VMware GitHub account when I noticed this project.

Platypus is an initiative to improve documentation across a number of VMware’s products as described using Open API and Swagger UI. This allows everyone to easily consume, and enhance VMware’s REST API’s & their usage. The products currently covered are vRA 7, vROps 6.2, vRO 7 and NSX 6.2.

Swagger is a simple yet powerful representation of your RESTful API. Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API.

Using Swagger UI is one step, but the biggest benefit of Platypus is that it is packaged and shipped in a container to improve its distribution: how cool is that? :)

Grant launched the project initially, but was joined by Roman, John and Paul since.

To start using it, you just have to run the Docker container:

docker run --rm --name platypus -p 80:8080 vmware/platypus

Initially only available for vRA API, the project** integrates now vROps, vRO and NSX APIs**. You can specify directly the product and its version with parameters in the docker run command line.

romain ~ docker run --name platypus --rm -p 80:8080 -e PRODUCT="nsx" -e VERSION="6.2" vmware/platypus
specifying your environment ..
starting your swaggerness
[20:32:57] Working directory changed to /app
[20:32:58] Using gulpfile /app/gulpfile.js
[20:32:58] Starting 'connect'...
[20:32:58] Finished 'connect' after 15 ms
[20:32:58] Starting 'copy-local-specs'...
[20:32:58] Server started http://localhost:8080
[20:32:58] LiveReload started on port 35729
[20:32:58] Finished 'copy-local-specs' after 35 ms
[20:32:58] Starting 'watch'...

Below is the result for the NSX 6.2 API…

…or also vRA 7 API documentation.

You have to expand the operations to gather details about a specific API call.

Note: some parts are currently missing (such as request body not present in some of the requests) but will soon be integrated.

Find out more at https://github.com/vmware/platypus.