Parameterized swagger support for API gateway

I know that Swagger integration for the API-gateway resources is on the CDK roadmap.

I think it can bring a lot of value, since at the moment, if you want to use (using CFN) a swagger file you can either inline it and reference CFN resources, or import it and not reference anything.

Typically, you’d want both - you want to separate the swagger file from your CFN/CDK code so that you can use all the fancy tools (UI editor / client generation / etc), but also usually you’d need to reference CFN resources (e.g. lambda integrations).

With CDK it can be possible to have a templated external swagger file, and use string replacements for the referenced resources.

Took this offline with @eladb who suggested something in the lines of:

new apigateway.RestApi(this, 'MyAPI', {
  swagger: Swagger.load('/path/to/swagger', {
    xxx: myLambdaFunction.functionName,
    yyy: myAuthenticator.functionArn
  }
});

I think it could bring huge value to CDK users as you can use the “API first” methodology and leverage all the existing swagger tools.

[andyRokit]

I think that the solution to this lies with CloudFormation rather than CDK.

Unlike API Gateway, the Step Functions resource supports the concept of DefinitionSubstitutions.

This would benefit CDK and CF (as it also requires a transformation to use variables) as well as remain consistent with CF’s current approach.

Assuming that property was added, the CDK code would be:

const myLambdaFunction = ...
const myApiGatewayRole = ...

const api = new apigateway.SpecRestApi(this, 'books-api', {
  apiDefinition: apigateway.ApiDefinition.fromAsset('path-to-file.json'),
  definitionSubstitutions: {
    'myLambdaFunctionArn': myLambdaFunction.functionArn,
    'myApiGatewayRoleArn': myApiGatewayRole.roleArn
  }
});

I’ve raised a feature request to the CloudFormation team asking for this property to be added. If it makes sense to anybody reading this issue, feel free to thumbs-up the issue.

[abbottdev]

At the moment I’m working around this by using the swagger-parser npm library to parse my swagger file on start up, and then dynamically add lambda integrations. Disclaimer I don’t know how well cdk will continue to handle running promises but as of 0.34.0 it works.

Hope this helps people workaround this until it’s implemented: https://gist.github.com/abbottdev/17379763ebc14a5ecbf2a111ffbcdd86

It may be a bit dynamic for people to want to use, it could always be refactored to use more explicitly defined lambda functions quite easily.