openapi-backend

The mockResponseForOperation(operationId) method resolves data based on your OpenAPI specification in the following priority:

1. OpenAPI example objects: If the response content contains an example field, that object is returned.
2. JSON Schema: If no example is present, it uses the schema definition to generate a mock object.

Example OpenAPI structure supported:

paths:
  '/pets':
    get:
      operationId: getPets
      responses:
        200:
          content:
            'application/json':
              example:
                - id: 1
                  name: Garfield
  '/pets/{id}':
    get:
      operationId: getPetById
      responses:
        200:
          content:
            'application/json':
              schema:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string, example: Garfield }

OpenAPIBackend does not validate responses automatically. To enable response validation, register a postResponseHandler.

When a postResponseHandler is registered, the return value of your operation handler is passed to context.response. You can then use api.validateResponse or api.validateResponseHeaders to check the validity of the response against the OpenAPI spec.

api.register({
  getPets: (c) => {
    // Return value is passed to context.response
    return [{ id: 1, name: 'Garfield' }];
  },
  postResponseHandler: (c, req, res) => {
    // Validate the body
    const valid = c.api.validateResponse(c.response, c.operation);
    if (valid.errors) {
      return res.status(502).json({ status: 502, err: valid.errors });
    }
    
    // Or validate headers
    const validHeaders = c.api.validateResponseHeaders(res.headers, c.operation, {
      statusCode: res.statusCode,
      setMatchType: 'exact',
    });
    if (validHeaders.errors) {
      return res.status(502).json({ status: 502, err: validHeaders.errors });
    }

    return res.status(200).json(c.response);
  },
});

This example demonstrates how to use openapi-backend within an AWS CDK infrastructure. To run this example, you must have NodeJS, NPM, AWS, and AWS CDK installed. If you wish to run tests or start the application locally, you also need AWS SAM CLI (>= v1.65) and Docker.

Prerequisites

1. AWS Authentication: Ensure you are authenticated with your AWS profile (e.g., via SSO).

   aws sso login --profile your-profile

2. CDK Bootstrap: The CDK environment must be bootstrapped for your specific AWS account and region.

   AWS_PROFILE=your-profile npx cdk bootstrap aws://YOUR_ACCOUNT_ID/YOUR_DEFAULT_REGION

Deployment

Deploy the stack using the following command:

AWS_PROFILE=your-profile npx cdk deploy

After deployment, locate the OpenAPIBackendHttpApiEndpoint in the command output. This is your API Gateway URL.

Testing the API

Set the deployed URL as an environment variable to simplify testing:

export CDK_OUTPUT_API_GW_URL=https://your-api-gateway-url.execute-api.region.amazonaws.com

# Test endpoints
curl -i "$CDK_OUTPUT_API_GW_URL/pets"
curl -i "$CDK_OUTPUT_API_GW_URL/pets/1"

To use openapi-backend, instantiate the OpenAPIBackend class with your OpenAPI definition (file path or object), register handlers for your operationIds, and call api.init().

Handlers receive a special Context object (c) as the first argument, which contains parsed request data, the matched operation, and validation results. Subsequent arguments follow your framework's signature (e.g., Express's req and res).

import OpenAPIBackend from 'openapi-backend';

// create api with your definition file or object
const api = new OpenAPIBackend({ definition: './petstore.yml' });

// register your framework specific request handlers here
api.register({
  getPets: (c, req, res) => res.status(200).json({ result: 'ok' }),
  getPetById: (c, req, res) => res.status(200).json({ result: 'ok' }),
  validationFail: (c, req, res) => res.status(400).json({ err: c.validation.errors }),
  notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),
});

// initalize the backend
api.init();