[apigateway] Support loading API gateway Model schemas from file

[4naesthetic]

API Gateway model schemas are currently specified using a JsonSchema type, which means writing the schema inline in your source code. I would like to be able to define API gateway models with schemas read from the local filesystem (preferably with syntax validation during synthesis).

Use Case

My project has API gateway models stored in files in the source directory which we want in a separate part of the source tree.

Proposed Solution

Could be implemented specifically for the API Gateway module, but it might make more sense to add an arbitrary JsonSchema.fromFile similar to what we have for assets.

Other

Current workaround is to add an empty schema when creating the model, read the JSON schema from file and override the Cfn Schema property. The major drawback of this approach is that schema changes alone no longer trigger redeployments automatically, as they aren't included in the hash when latestDeployment is deciding whether a redeployment is required.

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

---

This is a 🚀 Feature Request

[nija-at]

Could you provide some samples on how these models are stored in your filesystem? How complex or big is your most most complex/biggest schema?

[4naesthetic]

Simplified package outline is something like:

<cdk-app-base>/<cdk-stack1>/apis
├── requirements.txt
├── schemas
│   ├── <resource1>
│   │   ├── create.req.json
│   │   └── update.req.json
|   |   └── ...
│   ├── <resource2>
│   │   ├── create.req.json
│   │   └── update.req.json
|   |   └── ...
│   └── <resource3>
│       ├── create.req.json
│       └── update.req.json
|       └── ...
└── <api-python-package>
    ├── __init__.py
    ├── common
    │   └── ...
    └── handlers
        ├── <resource1>
        │   ├── create.py
        │   ├── update.py
        |   └── ...
        ├── <resource2>
        │   ├── create.py
        │   ├── update.py
        |   └── ...
        └── <resource3>
            ├── create.py
            ├── update.py
            └── ...

Our schemas are quite simple. Request models typically consist of up to 4 string parameters with validation (no significant deep-object nesting).

[amwill04]

If anyone finds this of use until an official method is created.

I use it only for specific set of schemas as a quick and dirty way - so it comes with a wanring!

import { JsonSchema, JsonSchemaVersion } from '@aws-cdk/aws-apigateway';

export const generateJSONSchemaFromObject = (input: any): JsonSchema => {
    const formattedSchema: any = {};
    for (const [key, value] of Object.entries(input)) {
        const formattedKey = keyFormatter(key);
        formattedSchema[formattedKey] = valueSwitcher(formattedKey, value);
    }
    return formattedSchema as JsonSchema;
};

const keyFormatter = (key: string): string => {
    if (key.startsWith('$')) {
        return key.slice(1);
    }
    return key;
};

const valueSwitcher = (key: string, value: any): any => {
    if (key === 'schema') {
        return schema(value as string);
    }
    switch (true) {
        case Array.isArray(value): {
            const newValues: any[] = [];
            for (const val of value) {
                newValues.push(valueSwitcher(key, val));
            }
            return newValues;
        }
        case typeof value === 'object':
            return generateJSONSchemaFromObject(value);
        default:
            return value;
    }
};

const schema = (value: string): JsonSchemaVersion => {
    if (value !== JsonSchemaVersion.DRAFT4) {
        throw new Error('api gateway model schema must be draft-04')
    }
    return JsonSchemaVersion.DRAFT4;
};

Updated to reflect api gateway only accepts draft-04

[thorbenheins]

+1

[ViktorMasnyi]

+1

[github-actions]

This issue has received a significant amount of attention so we are automatically upgrading its priority. A member of the community will see the re-prioritization and provide an update on the issue.

[otaviomacedo]

This is essentially the same issue as #20055, which asks for support for a generic object (without the JsonSchemaType) to store the Json schema. Assuming we come up with a solution like:

const analyticsEventInputSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' }
  }
}

const analyticsEventModel = api.addModel("AnalyticsEvent", {
  modelName: "AnalyticsEvent",
  contentType: "application/json",

  // Not sure what the API would look like, exactly. 
  // But some sort of transform function would be involved here.
  schema: JsonSchemas.fromObject(analyticsEventInputSchema),
});

then, loading the spec from a file is something that can be done without special CDK support:

const schema = JsonSchemas.fromObject(
	JSON.parse(fs.readFileSync(fileName, { encoding: 'utf-8' }))
);

Closing as duplicate.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.