@flipdish/cdk-constructs

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

Installation

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

Basic Example

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 };
}

OpenAPI Utilities

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.

Types

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.

Testing

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.