@flipdish/cdk-constructs

CDK Constructs for Flipdish serverless applications, with a focus on API constructs that provide automatic OpenAPI documentation generation and deployment.

Installation

``bash
npm install @flipdish/cdk-constructs
`

Overview

This package provides CDK constructs and utilities for building serverless APIs with strong typing and automatic OpenAPI documentation. It is designed to be used with SST and integrates with Zod for schema validation and OpenAPI generation.

Features

- Api Construct: Drop-in replacement for SST's Api construct, with built-in OpenAPI documentation generation.
- Automatic OpenAPI Docs: Generates and deploys OpenAPI JSON, YAML, and HTML documentation for your API routes.
- Schema Integration: Supports Zod-based schema definitions for routes.
- TypeScript-first: All constructs and utilities are strictly typed.

Usage

$3

`typescript
import { Api, SchemaFunction } from '@flipdish/cdk-constructs';
import { z } from 'zod';
import { StackContext } from 'sst/constructs';

export function API({ stack }: StackContext) {
const api = new Api(stack, 'Api', {
routes: {
'GET /hello': {
function: new SchemaFunction(stack, 'HelloHandler', {
handler: 'src/hello.handler',
schema: {
responses: {
200: z.object({ message: z.string() }),
},
},
}),
},
},
});

// The following endpoints are automatically added:
// - /openapi.json
// - /openapi.yaml
// - /openapi.html

return { api };
}
`

$3

You can also use the following utilities for advanced OpenAPI schema generation:

- buildSchema(registry, serviceName, url): Generates an OpenAPI schema document from a registry.
- sstRoutesToOpenApiSchema(routes): Converts SST route definitions to OpenAPI route configs.

$3

The package exports several types to help with strong typing and schema integration:

- Schema
- SchemaFunction
- SchemaFunctionProps
- SchemaRouteProps
- SchemaApiProps
- SchemaApiFunctionRouteProps`

Development & Testing

This package is maintained in the serverless-app-template repository.

$3

You can test the constructs by deploying a stack and verifying that the OpenAPI documentation endpoints are available and accurate. For unit testing, use your preferred test runner (e.g., Vitest or Jest) to check that the constructs behave as expected.

License

MIT

Contributing

This package is maintained in the serverless-app-template repository.