# AssetApiDefinition

OpenAPI specification from a local file.

Extends: ApiDefinition › AssetApiDefinition

- Source: [`aws-apigateway/lib/api-definition.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-apigateway/lib/api-definition.ts#L185)
- Type last changed: v2.224.0 · 13 Nov 2025

## Example

```ts
const myApiDefinition = apigateway.ApiDefinition.fromAsset('path-to-file.json');
const specRestApi = new apigateway.SpecRestApi(this, 'my-specrest-api', {
  deploy: false,
  apiDefinition: myApiDefinition
});

// Use `stageName` to deploy to an existing stage
const deployment = new apigateway.Deployment(this, 'my-deployment', {
  api: specRestApi,
  stageName: 'dev',
  retainDeployments: true, // keep old deployments
});

// Trigger a new deployment on OpenAPI definition updates
deployment.addToLogicalId(myApiDefinition);
```

## Initializer

```ts
new AssetApiDefinition(path: string, options?: AssetOptions)
```

## Methods

- `bind(scope: Construct): ApiDefinitionConfig` — Called when the specification is initialized to allow this object to bind to the stack, add resources and have fun.

- `bindAfterCreate(scope: Construct, restApi: IRestApiRef): void` — Called after the CFN RestApi resource has been created to allow the Api Definition to bind to it.

  Specifically it's required to allow assets to add
  metadata for tooling like SAM CLI to be able to find their origins.

- `fromAsset(file: string, options?: AssetOptions): AssetApiDefinition // chainable` (static) — Loads the API specification from a local disk asset.

- `fromBucket(bucket: IBucket, key: string, objectVersion?: string): S3ApiDefinition` (static) — Creates an API definition from a specification file in an S3 bucket.

- `fromInline(definition: any): InlineApiDefinition` (static) — Create an API definition from an inline object.

  The inline object must follow the
  schema of OpenAPI 2.0 or OpenAPI 3.0

  ```ts
    apigateway.ApiDefinition.fromInline({
      openapi: '3.0.2',
      paths: {
        '/pets': {
          get: {
            'responses': {
              200: {
                content: {
                  'application/json': {
                    schema: {
                      $ref: '#/components/schemas/Empty',
                    },
                  },
                },
              },
            },
            'x-amazon-apigateway-integration': {
              responses: {
                default: {
                  statusCode: '200',
                },
              },
              requestTemplates: {
                'application/json': '{"statusCode": 200}',
              },
              passthroughBehavior: 'when_no_match',
              type: 'mock',
            },
          },
        },
      },
      components: {
        schemas: {
          Empty: {
            title: 'Empty Schema',
            type: 'object',
          },
        },
      },
    });
  ```