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:

path.user.post=http://3.64.241.104:12121/user/post

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

path.user.post=http://3.64.241.104:12121user/post,authorizer1,user.email,user.id

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:

tag.Frontend=http://3.64.241.105:12121

This path will be extended to use the endpoint: http://3.64.241.105:12121/user/post

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:

configuration=filename

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
authorizer.name=DubaixCognito,Other
authorizer.identity-source=$request.header.Authorization
authorizer.audience=2f0m9fcoiejij4316u574aq259,7ac34sujrb8gmvj2b6blpi7ruu
authorizer.issuer=https://cognito-idp.eu-west-2.amazonaws.com/eu-west-2_1T9bfKHNp

tag.Frontend=http://3.64.241.104:12121/tmp/,DubaixCognito,user.email,user.id
path.user.scope2=http://OTHER_PATH:12122/path,Other,user.email

Usage

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