Skip to content

registry upload openapi

Jump to bottom
Tim Burks edited this page Feb 16, 2023 · 4 revisions

The registry tool includes an opinionated uploader that imports OpenAPI descriptions into the registry. It is designed to import API descriptions from github.com/APIs-guru/openapi-directory but will work with other API descriptions stored in a similar structure.

The uploader makes these assumptions:

  • All API descriptions are stored on the local filesystem and under a common top-level directory. For the OpenAPI directory, this is the APIs directory.

  • Each API spec is in a subdirectory of this top-level directory that is named with the corresponding API version. Version name styles vary widely, so for this we simply assume that the name of the lowest-level directory is the version name.

  • The version name is assumed to be the name of a version of an API. Due to a nuance of the OpenAPI Specification, this may not be true for these examples. In the OpenAPI Directory, version directory names are determined by the values in the version fields of the OpenAPI docuuments. But according to the OpenAPI Specification, version names in OpenAPI documents describe the version of the document and not the of API. We find there is considerable confusion over this, and since this is a sample/experimental import, we make the assumption that the directory name is the name of the API version. Note that the importer only considers the directory name and doesn't look at the value of the version field in the OpenAPI document.

  • OpenAPI documents are in files named either swagger.yaml or openapi.yaml. WARNING: if your spec is stored with a different filename, we'll miss it. Please let us know if you think we should support other names or file extensions (.yml? .json?).

  • OpenAPI documents are stored in a single file and are complete, i.e. "fully-resolved", with no references to external files.

  • The name of the API is derived from the remaining directories containing the API description, e.g. the Apigee Registry API is described in googleapis.com/apigeeregistry/v1 and the derived name of the API is googleapis.com-apigeeregistry.

The upload command is as follows:

registry upload openapi $DIRECTORY --project-id $PROJECTID

Here $DIRECTORY is the top-level directory of API description files (typically openapi-directory/APIs). This is a "bulk" uploader; it will upload every API spec that it finds meeting the above criteria. With the optional --base-uri argument, we can specify the root of a path to be stored in each spec's source_uri field. Here we include the commit id from the cloned Git repository:

# Get the commit hash of the checked-out specs directory
export COMMIT=`(cd $DIRECTORY; git rev-parse HEAD)`
registry upload openapi $DIRECTORY \
	--project-id $PROJECT \
	--base-uri https://github.com/apis-guru/openapi-directory/blob/$COMMIT

With these API descriptions stored in the registry, we can run linters and other tools by reading API specs from the registry, analyzing them, and putting the results back in the registry. Since each API spec is independent and fully-resolved, these tools can run concurrently and in a distributed way.

Clone this wiki locally