This article walks through the process of converting service specific OpenAPI specifications from Google Discovery REST URLs using Python.
Full code for this article can be found at stackql/google-discovery-to-openapi
Google publishes JSON specifications for all of their APIs (including GCP services as well as other APIs associated with other products - like analytics or workspace). These specifications can be accessed without authentication starting with the root document (https://discovery.googleapis.com/discovery/v1/apis) which contains metadata and the URL for each service specific document (for services like
The program fetches the service document for each service that is included and not explicitly excluded (configured through variables in the program). Non preferred services (beta or alpha versions) can be included by setting the variable
An OpenAPI spec is constructed for each service based upon the data in the service discovery doc. In many cases this is a straightforward one to one mapping, such as to top level
description values, it gets more complicated with parameters and schemas where some extra logic is required to keep the json pointers (
Extracting Paths and Verbs
The real magic is in extracting paths and verbs in a compliant OpenAPI format, as Google nests this data (potentially multiple levels deep) under resources.
The first step is to identify
methods nested under a
resources object (which can be mapped to operations - with a path and HTTP verb required to populate an OpenAPI spec), this function does this:
Now each method can be processed yielding an operation (combination of
verb), this is done using this function:
Full source code can be found at stackql/google-discovery-to-openapi.
if you have enjoyed this post, please consider buying me a coffee ☕ to help me keep writing!