16th Dec 2021

Openapi 4 AWS command line interface

This is utility to enrich an openapi specification with information specific for the AWS API Gateway. It allows defining route integrations and authorizers to do automatic (re-)imports in API Gateway.

There is a maven plugin covering this functionality, as well as a standalone python version

Security / Authorizers

To specify an authorizer, use the following mandatory parameters:

  • authorizer.name: name of the authorizer
  • authorizer.identity-source: header containing the authorization, like: $request.header.Authorization
  • authorizer.audience: comma separated list of audiences for this authorizer.
  • authorizer.issuer

The following two parameters are currently optional:

  • authorizer.authorization-type=oauth2: currently, it can be only defined as "oauth2".
  • authorizer.type=jwt: currently, it can be only defined as "jwt".

Multiple authorizers can be defined using a comma separated list in authorizer.name, i.e.:

authorizer.name=authorizer1, authorizer2

It is possible then to specify a different parameter for each authorizer using the syntax:

  • authorizer.audience.AUTHORIZER_NAME=audience
  • authorizer.issuer.AUTHORIZER_NAME=issuer

Paths / Integrations

To define routes, the syntax is:

  • path.PATH=full_uri[,authorizer_name,scopes]*

For example:


This will define an endpoint for the route /user/post, using no authorizers. Alternatively, authorizer plus scopes can be specified:


In this case, it uses the authorizer with name "authorizer1", with scopes "user.email" and "user.id"

Paths / Integrations Using tags

A better option to define integrations is defining openapi tags associated for that path, and using then the following parameters:

  • tag.TAG=uri[,authorizer_name,scopes]*

For example, if a route /user/post has an associated tag Frontend, and we define:


This path will be extended to use the endpoint:

Defining input / output

Three parameters manage the input / output tasks:

  • filename: allows to specify the input files to process, and it is possible to repeat this parameter multiple times. It is an error if the designed filename does not exist.
  • glob: which supports specifying the input using filename patterns. It is not an error if this pattern matches no names in the file system.
  • output-folder: optional, defines the output folder. If not specified, the input files will be overwritten.

Defining the configuration in a separate file

It is possible to specify any configuration parameters in a separate file, using the argument:


This file should define the parameters in separate lines, using the same syntax. Empty lines and starting with the character **#** are discarded.

It is possible to specify multiple external configuration files.

An example of such a file would be just:

# a simple comment



To use the utility from the command line, build it or download from maven central. The version with built-in dependencies is available as (link depends on version used): https://repo1.maven.org/maven2/net/coderazzi/openapi4aws/1.1.1/openapi4aws-1.1.1-jar-with-dependencies.jar

java -jar openapi4aws-1.0.2-jar-with-dependencies.jar --configuration=conf.prop