# API Reference ## Constructs ### Api AWS API Gateway REST API defined with OpenApi v3 schema. #### Initializers ```typescript import { Api } from '@alma-cdk/openapix' new Api(scope: Construct, id: string, props: ApiProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | ApiProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* ApiProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | applyRemovalPolicy | Apply the given removal policy to this resource. | | addApiKey | Add an ApiKey to the deploymentStage. | | addDomainName | Defines an API Gateway domain name and maps it to this API. | | addGatewayResponse | Adds a new gateway response. | | addToResourcePolicy | Adds a statement to the resource policy associated with this rest api. | | addUsagePlan | Adds a usage plan. | | arnForExecuteApi | Gets the "execute-api" ARN. | | grantInvokeFromVpcEndpointsOnly | Add a resource policy that only allows API execution from a VPC Endpoint to create a private API. | | metric | Returns the given named metric for this API. | | metricCacheHitCount | Metric for the number of requests served from the API cache in a given period. | | metricCacheMissCount | Metric for the number of requests served from the backend in a given period, when API caching is enabled. | | metricClientError | Metric for the number of client-side errors captured in a given period. | | metricCount | Metric for the total number API requests in a given period. | | metricIntegrationLatency | Metric for the time between when API Gateway relays a request to the backend and when it receives a response from the backend. | | metricLatency | The time between when API Gateway receives a request from a client and when it returns a response to the client. | | metricServerError | Metric for the number of server-side errors captured in a given period. | | urlForPath | Returns the URL for an HTTP path. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `applyRemovalPolicy` ```typescript public applyRemovalPolicy(policy: RemovalPolicy): void ``` Apply the given removal policy to this resource. The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced. The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS account for data recovery and cleanup later (`RemovalPolicy.RETAIN`). ###### `policy`^Required - *Type:* aws-cdk-lib.RemovalPolicy --- ##### `addApiKey` ```typescript public addApiKey(id: string, options?: ApiKeyOptions): IApiKey ``` Add an ApiKey to the deploymentStage. ###### `id`^Required - *Type:* string --- ###### `options`^Optional - *Type:* aws-cdk-lib.aws_apigateway.ApiKeyOptions --- ##### `addDomainName` ```typescript public addDomainName(id: string, options: DomainNameOptions): DomainName ``` Defines an API Gateway domain name and maps it to this API. ###### `id`^Required - *Type:* string The construct id. --- ###### `options`^Required - *Type:* aws-cdk-lib.aws_apigateway.DomainNameOptions custom domain options. --- ##### `addGatewayResponse` ```typescript public addGatewayResponse(id: string, options: GatewayResponseOptions): GatewayResponse ``` Adds a new gateway response. ###### `id`^Required - *Type:* string --- ###### `options`^Required - *Type:* aws-cdk-lib.aws_apigateway.GatewayResponseOptions --- ##### `addToResourcePolicy` ```typescript public addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult ``` Adds a statement to the resource policy associated with this rest api. A resource policy will be automatically created upon the first call to `addToResourcePolicy`. Note that this does not work with imported rest api. ###### `statement`^Required - *Type:* aws-cdk-lib.aws_iam.PolicyStatement The policy statement to add. --- ##### `addUsagePlan` ```typescript public addUsagePlan(id: string, props?: UsagePlanProps): UsagePlan ``` Adds a usage plan. ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* aws-cdk-lib.aws_apigateway.UsagePlanProps --- ##### `arnForExecuteApi` ```typescript public arnForExecuteApi(method?: string, path?: string, stage?: string): string ``` Gets the "execute-api" ARN. ###### `method`^Optional - *Type:* string --- ###### `path`^Optional - *Type:* string --- ###### `stage`^Optional - *Type:* string --- ##### `grantInvokeFromVpcEndpointsOnly` ```typescript public grantInvokeFromVpcEndpointsOnly(vpcEndpoints: IVpcEndpoint[]): void ``` Add a resource policy that only allows API execution from a VPC Endpoint to create a private API. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-examples.html#apigateway-resource-policies-source-vpc-example](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-examples.html#apigateway-resource-policies-source-vpc-example) ###### `vpcEndpoints`^Required - *Type:* aws-cdk-lib.aws_ec2.IVpcEndpoint[] the interface VPC endpoints to grant access to. --- ##### `metric` ```typescript public metric(metricName: string, props?: MetricOptions): Metric ``` Returns the given named metric for this API. ###### `metricName`^Required - *Type:* string --- ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricCacheHitCount` ```typescript public metricCacheHitCount(props?: MetricOptions): Metric ``` Metric for the number of requests served from the API cache in a given period. Default: sum over 5 minutes ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricCacheMissCount` ```typescript public metricCacheMissCount(props?: MetricOptions): Metric ``` Metric for the number of requests served from the backend in a given period, when API caching is enabled. Default: sum over 5 minutes ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricClientError` ```typescript public metricClientError(props?: MetricOptions): Metric ``` Metric for the number of client-side errors captured in a given period. Default: sum over 5 minutes ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricCount` ```typescript public metricCount(props?: MetricOptions): Metric ``` Metric for the total number API requests in a given period. Default: sample count over 5 minutes ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricIntegrationLatency` ```typescript public metricIntegrationLatency(props?: MetricOptions): Metric ``` Metric for the time between when API Gateway relays a request to the backend and when it receives a response from the backend. Default: average over 5 minutes. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricLatency` ```typescript public metricLatency(props?: MetricOptions): Metric ``` The time between when API Gateway receives a request from a client and when it returns a response to the client. The latency includes the integration latency and other API Gateway overhead. Default: average over 5 minutes. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricServerError` ```typescript public metricServerError(props?: MetricOptions): Metric ``` Metric for the number of server-side errors captured in a given period. Default: sum over 5 minutes ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `urlForPath` ```typescript public urlForPath(path?: string): string ``` Returns the URL for an HTTP path. Fails if `deploymentStage` is not set either by `deploy` or explicitly. ###### `path`^Optional - *Type:* string --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | isOwnedResource | Returns true if the construct was created by CDK, and false otherwise. | | isResource | Check whether the given construct is a Resource. | --- ##### `isConstruct` ```typescript import { Api } from '@alma-cdk/openapix' Api.isConstruct(x: any) ``` Checks if `x` is a construct. Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked. Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead. ###### `x`^Required - *Type:* any Any object. --- ##### `isOwnedResource` ```typescript import { Api } from '@alma-cdk/openapix' Api.isOwnedResource(construct: IConstruct) ``` Returns true if the construct was created by CDK, and false otherwise. ###### `construct`^Required - *Type:* constructs.IConstruct --- ##### `isResource` ```typescript import { Api } from '@alma-cdk/openapix' Api.isResource(construct: IConstruct) ``` Check whether the given construct is a Resource. ###### `construct`^Required - *Type:* constructs.IConstruct --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | env | aws-cdk-lib.ResourceEnvironment | The environment this resource belongs to. | | stack | aws-cdk-lib.Stack | The stack in which this resource is defined. | | restApiId | string | The ID of this API Gateway RestApi. | | restApiName | string | A human friendly name for this Rest API. | | restApiRef | aws-cdk-lib.aws_apigateway.RestApiReference | A reference to a RestApi resource. | | restApiRootResourceId | string | The resource ID of the root resource. | | root | aws-cdk-lib.aws_apigateway.IResource | Represents the root resource of this API endpoint ('/'). | | url | string | The deployed root URL of this REST API. | | domainName | aws-cdk-lib.aws_apigateway.DomainName | The first domain name mapped to this API, if defined through the `domainName` configuration prop, or added via `addDomainName`. | | latestDeployment | aws-cdk-lib.aws_apigateway.Deployment | API Gateway deployment that represents the latest changes of the API. | | deploymentStage | aws-cdk-lib.aws_apigateway.Stage | API Gateway stage that points to the latest deployment (if defined). | | document | IDocument | The final OpenApi v3 document used to generate the AWS API Gateway. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `env`^Required ```typescript public readonly env: ResourceEnvironment; ``` - *Type:* aws-cdk-lib.ResourceEnvironment The environment this resource belongs to. For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into. --- ##### `stack`^Required ```typescript public readonly stack: Stack; ``` - *Type:* aws-cdk-lib.Stack The stack in which this resource is defined. --- ##### `restApiId`^Required ```typescript public readonly restApiId: string; ``` - *Type:* string The ID of this API Gateway RestApi. --- ##### `restApiName`^Required ```typescript public readonly restApiName: string; ``` - *Type:* string A human friendly name for this Rest API. Note that this is different from `restApiId`. --- ##### `restApiRef`^Required ```typescript public readonly restApiRef: RestApiReference; ``` - *Type:* aws-cdk-lib.aws_apigateway.RestApiReference A reference to a RestApi resource. --- ##### `restApiRootResourceId`^Required ```typescript public readonly restApiRootResourceId: string; ``` - *Type:* string The resource ID of the root resource. --- ##### `root`^Required ```typescript public readonly root: IResource; ``` - *Type:* aws-cdk-lib.aws_apigateway.IResource Represents the root resource of this API endpoint ('/'). Resources and Methods are added to this resource. --- ##### `url`^Required ```typescript public readonly url: string; ``` - *Type:* string The deployed root URL of this REST API. --- ##### `domainName`^Optional ```typescript public readonly domainName: DomainName; ``` - *Type:* aws-cdk-lib.aws_apigateway.DomainName The first domain name mapped to this API, if defined through the `domainName` configuration prop, or added via `addDomainName`. --- ##### `latestDeployment`^Optional ```typescript public readonly latestDeployment: Deployment; ``` - *Type:* aws-cdk-lib.aws_apigateway.Deployment API Gateway deployment that represents the latest changes of the API. This resource will be automatically updated every time the REST API model changes. This will be undefined if `deploy` is false. --- ##### `deploymentStage`^Required ```typescript public readonly deploymentStage: Stage; ``` - *Type:* aws-cdk-lib.aws_apigateway.Stage API Gateway stage that points to the latest deployment (if defined). If `deploy` is disabled, you will need to explicitly assign this value in order to set up integrations. --- ##### `document`^Required ```typescript public readonly document: IDocument; ``` - *Type:* IDocument The final OpenApi v3 document used to generate the AWS API Gateway. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | PROPERTY_INJECTION_ID | string | Uniquely identifies this class. | --- ##### `PROPERTY_INJECTION_ID`^Required ```typescript public readonly PROPERTY_INJECTION_ID: string; ``` - *Type:* string Uniquely identifies this class. --- ### CognitoUserPoolsAuthorizer #### Initializers ```typescript import { CognitoUserPoolsAuthorizer } from '@alma-cdk/openapix' new CognitoUserPoolsAuthorizer(scope: Construct, id: string, props: CognitoUserPoolsAuthorizerProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | CognitoUserPoolsAuthorizerProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* CognitoUserPoolsAuthorizerProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { CognitoUserPoolsAuthorizer } from '@alma-cdk/openapix' CognitoUserPoolsAuthorizer.isConstruct(x: any) ``` Checks if `x` is a construct. Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked. Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead. ###### `x`^Required - *Type:* any Any object. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | id | string | *No description.* | | xAmazonApigatewayAuthorizer | XAmazonApigatewayAuthorizer | *No description.* | | xAmazonApigatewayAuthtype | string | *No description.* | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `id`^Required ```typescript public readonly id: string; ``` - *Type:* string --- ##### `xAmazonApigatewayAuthorizer`^Required ```typescript public readonly xAmazonApigatewayAuthorizer: XAmazonApigatewayAuthorizer; ``` - *Type:* XAmazonApigatewayAuthorizer --- ##### `xAmazonApigatewayAuthtype`^Required ```typescript public readonly xAmazonApigatewayAuthtype: string; ``` - *Type:* string --- ### LambdaAuthorizer #### Initializers ```typescript import { LambdaAuthorizer } from '@alma-cdk/openapix' new LambdaAuthorizer(scope: Construct, id: string, props: LambdaAuthorizerProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | LambdaAuthorizerProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* LambdaAuthorizerProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | grantFunctionInvoke | Allow Lambda invoke action to be performed by given identity. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `grantFunctionInvoke` ```typescript public grantFunctionInvoke(api: IRestApi): void ``` Allow Lambda invoke action to be performed by given identity. The ARN format for authorizers is different compared to integrations when granting permissions, ex. arn:aws:execute-api:us-east-1:123456789012:api-id/authorizers/authorizer-id ###### `api`^Required - *Type:* aws-cdk-lib.aws_apigateway.IRestApi --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { LambdaAuthorizer } from '@alma-cdk/openapix' LambdaAuthorizer.isConstruct(x: any) ``` Checks if `x` is a construct. Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked. Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead. ###### `x`^Required - *Type:* any Any object. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | fn | aws-cdk-lib.aws_lambda.IFunction | *No description.* | | id | string | *No description.* | | xAmazonApigatewayAuthorizer | XAmazonApigatewayAuthorizer | *No description.* | | xAmazonApigatewayAuthtype | string | *No description.* | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `fn`^Required ```typescript public readonly fn: IFunction; ``` - *Type:* aws-cdk-lib.aws_lambda.IFunction --- ##### `id`^Required ```typescript public readonly id: string; ``` - *Type:* string --- ##### `xAmazonApigatewayAuthorizer`^Required ```typescript public readonly xAmazonApigatewayAuthorizer: XAmazonApigatewayAuthorizer; ``` - *Type:* XAmazonApigatewayAuthorizer --- ##### `xAmazonApigatewayAuthtype`^Required ```typescript public readonly xAmazonApigatewayAuthtype: string; ``` - *Type:* string --- ## Structs ### ApiBaseProps BaseProps for the `Api` construct without `RestApiProps`. #### Initializer ```typescript import { ApiBaseProps } from '@alma-cdk/openapix' const apiBaseProps: ApiBaseProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | source | string \| Schema | OpenApi Schema Definition source configuration. | | authorizers | AuthorizerConfig[] | Cognito User Pool or Custom Lambda based Authorizer configurations. | | defaultCors | CorsIntegration | Default CORS configuration. Applied to all path integrations. | | defaultIntegration | Integration | Add a default integration for paths without explicitly defined integrations. | | injections | {[ key: string ]: any} | Inject any OpenApi v3 data to given schema definition object paths. | | paths | Paths | Integrations for OpenApi Path definitions. | | rejections | string[] | Reject fields by absolute object path from generated definition. | | rejectionsDeep | string[] | Reject all matching fields from generated definition. | | upload | boolean | Schema Definition location (inline vs. | | validators | {[ key: string ]: Validator} | Configure availalbe request validators. API Gateway REST APIs can perform request parameter and request body validation. | --- ##### `source`^Required ```typescript public readonly source: string | Schema; ``` - *Type:* string | Schema OpenApi Schema Definition source configuration. Provide either string path to source or an instance of `openapix.Schema`. --- *Example* ```typescript const props: openapix.SchemaProps; new openapix.Schema(props) ``` ##### `authorizers`^Optional ```typescript public readonly authorizers: AuthorizerConfig[]; ``` - *Type:* AuthorizerConfig[] Cognito User Pool or Custom Lambda based Authorizer configurations. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) --- *Example* ```typescript [ new openapix.CognitoUserPoolsAuthorizer(this, 'MyCognitoAuthorizer', { cognitoUserPools: [userPool], resultsCacheTtl: Duration.minutes(5), }), ] ``` ##### `defaultCors`^Optional ```typescript public readonly defaultCors: CorsIntegration; ``` - *Type:* CorsIntegration Default CORS configuration. Applied to all path integrations. You can add path specific overrides by adding an `options` method with `new openapix.CorsIntegration(...)` integration. --- *Example* ```typescript new openapix.CorsIntegration(this, { headers: 'Content-Type,X-Amz-Date,Authorization', origins: '*', methods: 'options,get', }), ``` ##### `defaultIntegration`^Optional ```typescript public readonly defaultIntegration: Integration; ``` - *Type:* Integration Add a default integration for paths without explicitly defined integrations. --- *Example* ```typescript { 'defaultIntegration': new openapix.LambdaIntegration(this, fn), } ``` ##### `injections`^Optional ```typescript public readonly injections: {[ key: string ]: any}; ``` - *Type:* {[ key: string ]: any} Inject any OpenApi v3 data to given schema definition object paths. --- *Example* ```typescript { "info.title": "FancyPantsAPI" } ``` ##### `paths`^Optional ```typescript public readonly paths: Paths; ``` - *Type:* Paths Integrations for OpenApi Path definitions. --- *Example* ```typescript { '/message': { post: new openapix.LambdaIntegration(this, fn), }, } ``` ##### `rejections`^Optional ```typescript public readonly rejections: string[]; ``` - *Type:* string[] Reject fields by absolute object path from generated definition. --- *Example* ```typescript ['info.description'] ``` ##### `rejectionsDeep`^Optional ```typescript public readonly rejectionsDeep: string[]; ``` - *Type:* string[] Reject all matching fields from generated definition. --- *Example* ```typescript ['example', 'examples'] ``` ##### `upload`^Optional ```typescript public readonly upload: boolean; ``` - *Type:* boolean - *Default:* false Schema Definition location (inline vs. S3 location). Set `true` to upload to S3 or `false` (default) to inline it into resulting CloudFormation template. --- ##### `validators`^Optional ```typescript public readonly validators: {[ key: string ]: Validator}; ``` - *Type:* {[ key: string ]: Validator} Configure availalbe request validators. API Gateway REST APIs can perform request parameter and request body validation. You can optionally specify one of them with `default: true` to promote it as the default validator applied to all integrations. For non-default validators, you must specify `validator: ''` prop in every integration you wish to use the given validator. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html) --- *Example* ```typescript { 'all': { validateRequestBody: true, validateRequestParameters: true, default: true, }, 'params-only' : { validateRequestBody: false, validateRequestParameters: true, }, } ``` ### ApiProps Props to configure `new openapix.Api`. #### Initializer ```typescript import { ApiProps } from '@alma-cdk/openapix' const apiProps: ApiProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | source | string \| Schema | OpenApi Schema Definition source configuration. | | authorizers | AuthorizerConfig[] | Cognito User Pool or Custom Lambda based Authorizer configurations. | | defaultCors | CorsIntegration | Default CORS configuration. Applied to all path integrations. | | defaultIntegration | Integration | Add a default integration for paths without explicitly defined integrations. | | injections | {[ key: string ]: any} | Inject any OpenApi v3 data to given schema definition object paths. | | paths | Paths | Integrations for OpenApi Path definitions. | | rejections | string[] | Reject fields by absolute object path from generated definition. | | rejectionsDeep | string[] | Reject all matching fields from generated definition. | | upload | boolean | Schema Definition location (inline vs. | | validators | {[ key: string ]: Validator} | Configure availalbe request validators. API Gateway REST APIs can perform request parameter and request body validation. | | restApiProps | aws-cdk-lib.aws_apigateway.RestApiProps | Props to configure the underlying CDK `apigateway.RestApi`. | --- ##### `source`^Required ```typescript public readonly source: string | Schema; ``` - *Type:* string | Schema OpenApi Schema Definition source configuration. Provide either string path to source or an instance of `openapix.Schema`. --- *Example* ```typescript const props: openapix.SchemaProps; new openapix.Schema(props) ``` ##### `authorizers`^Optional ```typescript public readonly authorizers: AuthorizerConfig[]; ``` - *Type:* AuthorizerConfig[] Cognito User Pool or Custom Lambda based Authorizer configurations. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) --- *Example* ```typescript [ new openapix.CognitoUserPoolsAuthorizer(this, 'MyCognitoAuthorizer', { cognitoUserPools: [userPool], resultsCacheTtl: Duration.minutes(5), }), ] ``` ##### `defaultCors`^Optional ```typescript public readonly defaultCors: CorsIntegration; ``` - *Type:* CorsIntegration Default CORS configuration. Applied to all path integrations. You can add path specific overrides by adding an `options` method with `new openapix.CorsIntegration(...)` integration. --- *Example* ```typescript new openapix.CorsIntegration(this, { headers: 'Content-Type,X-Amz-Date,Authorization', origins: '*', methods: 'options,get', }), ``` ##### `defaultIntegration`^Optional ```typescript public readonly defaultIntegration: Integration; ``` - *Type:* Integration Add a default integration for paths without explicitly defined integrations. --- *Example* ```typescript { 'defaultIntegration': new openapix.LambdaIntegration(this, fn), } ``` ##### `injections`^Optional ```typescript public readonly injections: {[ key: string ]: any}; ``` - *Type:* {[ key: string ]: any} Inject any OpenApi v3 data to given schema definition object paths. --- *Example* ```typescript { "info.title": "FancyPantsAPI" } ``` ##### `paths`^Optional ```typescript public readonly paths: Paths; ``` - *Type:* Paths Integrations for OpenApi Path definitions. --- *Example* ```typescript { '/message': { post: new openapix.LambdaIntegration(this, fn), }, } ``` ##### `rejections`^Optional ```typescript public readonly rejections: string[]; ``` - *Type:* string[] Reject fields by absolute object path from generated definition. --- *Example* ```typescript ['info.description'] ``` ##### `rejectionsDeep`^Optional ```typescript public readonly rejectionsDeep: string[]; ``` - *Type:* string[] Reject all matching fields from generated definition. --- *Example* ```typescript ['example', 'examples'] ``` ##### `upload`^Optional ```typescript public readonly upload: boolean; ``` - *Type:* boolean - *Default:* false Schema Definition location (inline vs. S3 location). Set `true` to upload to S3 or `false` (default) to inline it into resulting CloudFormation template. --- ##### `validators`^Optional ```typescript public readonly validators: {[ key: string ]: Validator}; ``` - *Type:* {[ key: string ]: Validator} Configure availalbe request validators. API Gateway REST APIs can perform request parameter and request body validation. You can optionally specify one of them with `default: true` to promote it as the default validator applied to all integrations. For non-default validators, you must specify `validator: ''` prop in every integration you wish to use the given validator. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html) --- *Example* ```typescript { 'all': { validateRequestBody: true, validateRequestParameters: true, default: true, }, 'params-only' : { validateRequestBody: false, validateRequestParameters: true, }, } ``` ##### `restApiProps`^Optional ```typescript public readonly restApiProps: RestApiProps; ``` - *Type:* aws-cdk-lib.aws_apigateway.RestApiProps Props to configure the underlying CDK `apigateway.RestApi`. --- ### AuthorizerConfig #### Initializer ```typescript import { AuthorizerConfig } from '@alma-cdk/openapix' const authorizerConfig: AuthorizerConfig = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | xAmazonApigatewayAuthorizer | XAmazonApigatewayAuthorizer | *No description.* | | xAmazonApigatewayAuthtype | string | *No description.* | | id | string | *No description.* | --- ##### `xAmazonApigatewayAuthorizer`^Required ```typescript public readonly xAmazonApigatewayAuthorizer: XAmazonApigatewayAuthorizer; ``` - *Type:* XAmazonApigatewayAuthorizer --- ##### `xAmazonApigatewayAuthtype`^Required ```typescript public readonly xAmazonApigatewayAuthtype: string; ``` - *Type:* string --- ##### `id`^Required ```typescript public readonly id: string; ``` - *Type:* string --- ### AuthorizerExtensions #### Initializer ```typescript import { AuthorizerExtensions } from '@alma-cdk/openapix' const authorizerExtensions: AuthorizerExtensions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | xAmazonApigatewayAuthorizer | XAmazonApigatewayAuthorizer | *No description.* | | xAmazonApigatewayAuthtype | string | *No description.* | --- ##### `xAmazonApigatewayAuthorizer`^Required ```typescript public readonly xAmazonApigatewayAuthorizer: XAmazonApigatewayAuthorizer; ``` - *Type:* XAmazonApigatewayAuthorizer --- ##### `xAmazonApigatewayAuthtype`^Required ```typescript public readonly xAmazonApigatewayAuthtype: string; ``` - *Type:* string --- ### AwsIntegrationProps #### Initializer ```typescript import { AwsIntegrationProps } from '@alma-cdk/openapix' const awsIntegrationProps: AwsIntegrationProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | service | string | The name of the integrated AWS service (e.g. `s3`). | | action | string | The AWS action to perform in the integration. | | actionParameters | {[ key: string ]: string} | Parameters for the action. | | integrationHttpMethod | string | The integration's HTTP method type. | | options | aws-cdk-lib.aws_apigateway.IntegrationOptions | Integration options, such as content handling, request/response mapping, etc. | | path | string | The path to use for path-base APIs. | | proxy | boolean | Use AWS_PROXY integration. | | region | string | The region of the integrated AWS service. | | subdomain | string | A designated subdomain supported by certain AWS service for fast host-name lookup. | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | --- ##### `service`^Required ```typescript public readonly service: string; ``` - *Type:* string The name of the integrated AWS service (e.g. `s3`). --- ##### `action`^Optional ```typescript public readonly action: string; ``` - *Type:* string The AWS action to perform in the integration. Use `actionParams` to specify key-value params for the action. Mutually exclusive with `path`. --- ##### `actionParameters`^Optional ```typescript public readonly actionParameters: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} Parameters for the action. `action` must be set, and `path` must be undefined. The action params will be URL encoded. --- ##### `integrationHttpMethod`^Optional ```typescript public readonly integrationHttpMethod: string; ``` - *Type:* string - *Default:* POST The integration's HTTP method type. --- ##### `options`^Optional ```typescript public readonly options: IntegrationOptions; ``` - *Type:* aws-cdk-lib.aws_apigateway.IntegrationOptions Integration options, such as content handling, request/response mapping, etc. --- ##### `path`^Optional ```typescript public readonly path: string; ``` - *Type:* string The path to use for path-base APIs. For example, for S3 GET, you can set path to `bucket/key`. For lambda, you can set path to `2015-03-31/functions/${function-arn}/invocations` Mutually exclusive with the `action` options. --- ##### `proxy`^Optional ```typescript public readonly proxy: boolean; ``` - *Type:* boolean - *Default:* false Use AWS_PROXY integration. --- ##### `region`^Optional ```typescript public readonly region: string; ``` - *Type:* string - *Default:* same region as the stack The region of the integrated AWS service. --- ##### `subdomain`^Optional ```typescript public readonly subdomain: string; ``` - *Type:* string A designated subdomain supported by certain AWS service for fast host-name lookup. --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ### CallbackObject A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. #### Initializer ```typescript import { CallbackObject } from '@alma-cdk/openapix' const callbackObject: CallbackObject = { ... } ``` ### CognitoUserPoolsAuthorizerProps #### Initializer ```typescript import { CognitoUserPoolsAuthorizerProps } from '@alma-cdk/openapix' const cognitoUserPoolsAuthorizerProps: CognitoUserPoolsAuthorizerProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | cognitoUserPools | aws-cdk-lib.aws_cognito.IUserPool[] | *No description.* | | resultsCacheTtl | aws-cdk-lib.Duration | *No description.* | --- ##### `cognitoUserPools`^Required ```typescript public readonly cognitoUserPools: IUserPool[]; ``` - *Type:* aws-cdk-lib.aws_cognito.IUserPool[] --- ##### `resultsCacheTtl`^Optional ```typescript public readonly resultsCacheTtl: Duration; ``` - *Type:* aws-cdk-lib.Duration --- ### ComponentsObject Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. #### Initializer ```typescript import { ComponentsObject } from '@alma-cdk/openapix' const componentsObject: ComponentsObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | callbacks | {[ key: string ]: ReferenceObject \| CallbackObject} | An object to hold reusable Callback Objects. | | examples | {[ key: string ]: ReferenceObject \| ExampleObject} | An object to hold reusable Example Objects. | | headers | {[ key: string ]: ReferenceObject \| HeaderObject} | An object to hold reusable Header Objects. | | links | {[ key: string ]: ReferenceObject \| LinkObject} | An object to hold reusable Link Objects. | | parameters | {[ key: string ]: ReferenceObject \| ParameterObject} | An object to hold reusable Parameter Objects. | | requestBodies | {[ key: string ]: ReferenceObject \| RequestBodyObject} | An object to hold reusable Request Body Objects. | | responses | {[ key: string ]: ReferenceObject \| ResponseObject} | An object to hold reusable Response Objects. | | schemas | {[ key: string ]: ReferenceObject \| SchemaObject} | An object to hold reusable Schema Objects. | | securitySchemes | {[ key: string ]: ReferenceObject \| SecuritySchemeObject} | An object to hold reusable Security Scheme Objects. | --- ##### `callbacks`^Optional ```typescript public readonly callbacks: {[ key: string ]: ReferenceObject | CallbackObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | CallbackObject} An object to hold reusable Callback Objects. --- ##### `examples`^Optional ```typescript public readonly examples: {[ key: string ]: ReferenceObject | ExampleObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | ExampleObject} An object to hold reusable Example Objects. --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: ReferenceObject | HeaderObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | HeaderObject} An object to hold reusable Header Objects. --- ##### `links`^Optional ```typescript public readonly links: {[ key: string ]: ReferenceObject | LinkObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | LinkObject} An object to hold reusable Link Objects. --- ##### `parameters`^Optional ```typescript public readonly parameters: {[ key: string ]: ReferenceObject | ParameterObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | ParameterObject} An object to hold reusable Parameter Objects. --- ##### `requestBodies`^Optional ```typescript public readonly requestBodies: {[ key: string ]: ReferenceObject | RequestBodyObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | RequestBodyObject} An object to hold reusable Request Body Objects. --- ##### `responses`^Optional ```typescript public readonly responses: {[ key: string ]: ReferenceObject | ResponseObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | ResponseObject} An object to hold reusable Response Objects. --- ##### `schemas`^Optional ```typescript public readonly schemas: {[ key: string ]: ReferenceObject | SchemaObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | SchemaObject} An object to hold reusable Schema Objects. --- ##### `securitySchemes`^Optional ```typescript public readonly securitySchemes: {[ key: string ]: ReferenceObject | SecuritySchemeObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | SecuritySchemeObject} An object to hold reusable Security Scheme Objects. --- ### ContactObject The contact information for the exposed API. #### Initializer ```typescript import { ContactObject } from '@alma-cdk/openapix' const contactObject: ContactObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | email | string | The email address of the contact person/organization. | | name | string | The identifying name of the contact person/organization. | | url | string | The URL pointing to the contact information. | --- ##### `email`^Optional ```typescript public readonly email: string; ``` - *Type:* string The email address of the contact person/organization. MUST be in the format of an email address. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string The identifying name of the contact person/organization. --- ##### `url`^Optional ```typescript public readonly url: string; ``` - *Type:* string The URL pointing to the contact information. MUST be in the format of a URL. --- ### CorsIntegrationProps #### Initializer ```typescript import { CorsIntegrationProps } from '@alma-cdk/openapix' const corsIntegrationProps: CorsIntegrationProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | | headers | string | *No description.* | | methods | string | *No description.* | | origins | string | *No description.* | --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ##### `headers`^Required ```typescript public readonly headers: string; ``` - *Type:* string --- ##### `methods`^Required ```typescript public readonly methods: string; ``` - *Type:* string --- ##### `origins`^Required ```typescript public readonly origins: string; ``` - *Type:* string --- ### DiscriminatorObject When request bodies or response payloads may be one of a number of different schemas, a discriminator object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, inline schemas will not be considered. #### Initializer ```typescript import { DiscriminatorObject } from '@alma-cdk/openapix' const discriminatorObject: DiscriminatorObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | propertyName | string | The name of the property in the payload that will hold the discriminator value. | | mapping | {[ key: string ]: string} | An object to hold mappings between payload values and schema names or references. | --- ##### `propertyName`^Required ```typescript public readonly propertyName: string; ``` - *Type:* string The name of the property in the payload that will hold the discriminator value. --- ##### `mapping`^Optional ```typescript public readonly mapping: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} An object to hold mappings between payload values and schema names or references. --- ### EncodingObject A single encoding definition applied to a single schema property. #### Initializer ```typescript import { EncodingObject } from '@alma-cdk/openapix' const encodingObject: EncodingObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowReserved | boolean | Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. | | contentType | string | The Content-Type for encoding a specific property. | | explode | boolean | When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. | | headers | {[ key: string ]: ReferenceObject \| HeaderObject} | A map allowing additional information to be provided as headers, for example Content-Disposition. | | style | string | Describes how a specific property value will be serialized depending on its type. | --- ##### `allowReserved`^Optional ```typescript public readonly allowReserved: boolean; ``` - *Type:* boolean Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ##### `contentType`^Optional ```typescript public readonly contentType: string; ``` - *Type:* string The Content-Type for encoding a specific property. Default value depends on the property type: for string with format being binary – application/octet-stream; for other primitive types – text/plain; for object - application/json; for array – the default is defined based on the inner type. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types. --- ##### `explode`^Optional ```typescript public readonly explode: boolean; ``` - *Type:* boolean When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When style is form, the default value is true. For all other styles, the default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: ReferenceObject | HeaderObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | HeaderObject} A map allowing additional information to be provided as headers, for example Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a multipart. --- ##### `style`^Optional ```typescript public readonly style: string; ``` - *Type:* string Describes how a specific property value will be serialized depending on its type. See Parameter Object for details on the style property. The behavior follows the same values as query parameters, including default values. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ### ExampleObject Example Object. #### Initializer ```typescript import { ExampleObject } from '@alma-cdk/openapix' const exampleObject: ExampleObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | Long description for the example. | | externalValue | string | A URL that points to the literal example. | | summary | string | Short description for the example. | | value | any | Embedded literal example. | --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string Long description for the example. CommonMark syntax MAY be used for rich text representation. --- ##### `externalValue`^Optional ```typescript public readonly externalValue: string; ``` - *Type:* string A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The value field and externalValue field are mutually exclusive. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string Short description for the example. --- ##### `value`^Optional ```typescript public readonly value: any; ``` - *Type:* any Embedded literal example. The value field and externalValue field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. --- ### Extensible Allow Open Api Extensions via `x-` prefixed values. #### Initializer ```typescript import { Extensible } from '@alma-cdk/openapix' const extensible: Extensible = { ... } ``` ### ExternalDocumentationObject Allows referencing an external resource for extended documentation. #### Initializer ```typescript import { ExternalDocumentationObject } from '@alma-cdk/openapix' const externalDocumentationObject: ExternalDocumentationObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | url | string | The URL for the target documentation. | | description | string | A short description of the target documentation. | --- ##### `url`^Required ```typescript public readonly url: string; ``` - *Type:* string The URL for the target documentation. Value MUST be in the format of a URL. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description of the target documentation. CommonMark syntax MAY be used for rich text representation. --- ### HeaderObject The Header Object follows the structure of the Parameter Object with the following changes:. 1. name MUST NOT be specified, it is given in the corresponding headers map. 2. in MUST NOT be specified, it is implicitly in header. 3. All traits that are affected by the location MUST be applicable to a location of header (for example, style). #### Initializer ```typescript import { HeaderObject } from '@alma-cdk/openapix' const headerObject: HeaderObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowEmptyValue | boolean | Sets the ability to pass empty-valued parameters. | | deprecated | boolean | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. | | description | string | A brief description of the parameter. | | required | boolean | Determines whether this parameter is mandatory. | --- ##### `allowEmptyValue`^Optional ```typescript public readonly allowEmptyValue: boolean; ``` - *Type:* boolean Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. --- ### HttpIntegrationProps #### Initializer ```typescript import { HttpIntegrationProps } from '@alma-cdk/openapix' const httpIntegrationProps: HttpIntegrationProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | httpMethod | string | HTTP method to use when invoking the backend URL. | | options | aws-cdk-lib.aws_apigateway.IntegrationOptions | Integration options, such as request/resopnse mapping, content handling, etc. | | proxy | boolean | Determines whether to use proxy integration or custom integration. | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | --- ##### `httpMethod`^Optional ```typescript public readonly httpMethod: string; ``` - *Type:* string - *Default:* GET HTTP method to use when invoking the backend URL. --- ##### `options`^Optional ```typescript public readonly options: IntegrationOptions; ``` - *Type:* aws-cdk-lib.aws_apigateway.IntegrationOptions - *Default:* defaults based on `IntegrationOptions` defaults Integration options, such as request/resopnse mapping, content handling, etc. --- ##### `proxy`^Optional ```typescript public readonly proxy: boolean; ``` - *Type:* boolean - *Default:* true Determines whether to use proxy integration or custom integration. --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ### InfoObject The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. #### Initializer ```typescript import { InfoObject } from '@alma-cdk/openapix' const infoObject: InfoObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | title | string | The title of the API. | | version | string | The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). | | contact | ContactObject | The contact information for the exposed API. | | description | string | A short description of the API. | | license | LicenseObject | The license information for the exposed API. | | termsOfService | string | A URL to the Terms of Service for the API. | --- ##### `title`^Required ```typescript public readonly title: string; ``` - *Type:* string The title of the API. --- ##### `version`^Required ```typescript public readonly version: string; ``` - *Type:* string The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). --- ##### `contact`^Optional ```typescript public readonly contact: ContactObject; ``` - *Type:* ContactObject The contact information for the exposed API. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description of the API. CommonMark syntax MAY be used for rich text representation. --- ##### `license`^Optional ```typescript public readonly license: LicenseObject; ``` - *Type:* LicenseObject The license information for the exposed API. --- ##### `termsOfService`^Optional ```typescript public readonly termsOfService: string; ``` - *Type:* string A URL to the Terms of Service for the API. MUST be in the format of a URL. --- ### IntegrationConfig Base integration config. #### Initializer ```typescript import { IntegrationConfig } from '@alma-cdk/openapix' const integrationConfig: IntegrationConfig = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | | type | InternalIntegrationType | *No description.* | --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType --- ### LambdaAuthorizerProps #### Initializer ```typescript import { LambdaAuthorizerProps } from '@alma-cdk/openapix' const lambdaAuthorizerProps: LambdaAuthorizerProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | authType | string | *No description.* | | fn | aws-cdk-lib.aws_lambda.IFunction | *No description.* | | identitySource | string | *No description.* | | type | string | *No description.* | | resultsCacheTtl | aws-cdk-lib.Duration | *No description.* | --- ##### `authType`^Required ```typescript public readonly authType: string; ``` - *Type:* string --- ##### `fn`^Required ```typescript public readonly fn: IFunction; ``` - *Type:* aws-cdk-lib.aws_lambda.IFunction --- ##### `identitySource`^Required ```typescript public readonly identitySource: string; ``` - *Type:* string --- *Example* ```typescript apigateway.IdentitySource.header('Authorization') ``` ##### `type`^Required ```typescript public readonly type: string; ``` - *Type:* string --- ##### `resultsCacheTtl`^Optional ```typescript public readonly resultsCacheTtl: Duration; ``` - *Type:* aws-cdk-lib.Duration --- ### LambdaIntegrationOptions #### Initializer ```typescript import { LambdaIntegrationOptions } from '@alma-cdk/openapix' const lambdaIntegrationOptions: LambdaIntegrationOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | cacheKeyParameters | string[] | A list of request parameters whose values are to be cached. | | cacheNamespace | string | An API-specific tag group of related cached parameters. | | connectionType | aws-cdk-lib.aws_apigateway.ConnectionType | The type of network connection to the integration endpoint. | | contentHandling | aws-cdk-lib.aws_apigateway.ContentHandling | Specifies how to handle request payload content type conversions. | | credentialsPassthrough | boolean | Requires that the caller's identity be passed through from the request. | | credentialsRole | aws-cdk-lib.aws_iam.IRole | An IAM role that API Gateway assumes. | | integrationResponses | aws-cdk-lib.aws_apigateway.IntegrationResponse[] | The response that API Gateway provides after a method's backend completes processing a request. | | passthroughBehavior | aws-cdk-lib.aws_apigateway.PassthroughBehavior | Specifies the pass-through behavior for incoming requests based on the Content-Type header in the request, and the available mapping templates specified as the requestTemplates property on the Integration resource. | | requestParameters | {[ key: string ]: string} | The request parameters that API Gateway sends with the backend request. | | requestTemplates | {[ key: string ]: string} | A map of Apache Velocity templates that are applied on the request payload. | | timeout | aws-cdk-lib.Duration | The maximum amount of time an integration will run before it returns without a response. | | vpcLink | aws-cdk-lib.aws_apigateway.IVpcLink | The VpcLink used for the integration. | | allowTestInvoke | boolean | Allow invoking method from AWS Console UI (for testing purposes). | | proxy | boolean | Use proxy integration or normal (request/response mapping) integration. | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | --- ##### `cacheKeyParameters`^Optional ```typescript public readonly cacheKeyParameters: string[]; ``` - *Type:* string[] A list of request parameters whose values are to be cached. It determines request parameters that will make it into the cache key. --- ##### `cacheNamespace`^Optional ```typescript public readonly cacheNamespace: string; ``` - *Type:* string An API-specific tag group of related cached parameters. --- ##### `connectionType`^Optional ```typescript public readonly connectionType: ConnectionType; ``` - *Type:* aws-cdk-lib.aws_apigateway.ConnectionType - *Default:* ConnectionType.VPC_LINK if `vpcLink` property is configured; ConnectionType.Internet otherwise. The type of network connection to the integration endpoint. --- ##### `contentHandling`^Optional ```typescript public readonly contentHandling: ContentHandling; ``` - *Type:* aws-cdk-lib.aws_apigateway.ContentHandling - *Default:* none if this property isn't defined, the request payload is passed through from the method request to the integration request without modification, provided that the `passthroughBehaviors` property is configured to support payload pass-through. Specifies how to handle request payload content type conversions. --- ##### `credentialsPassthrough`^Optional ```typescript public readonly credentialsPassthrough: boolean; ``` - *Type:* boolean - *Default:* Caller identity is not passed through Requires that the caller's identity be passed through from the request. --- ##### `credentialsRole`^Optional ```typescript public readonly credentialsRole: IRole; ``` - *Type:* aws-cdk-lib.aws_iam.IRole - *Default:* A role is not assumed An IAM role that API Gateway assumes. Mutually exclusive with `credentialsPassThrough`. --- ##### `integrationResponses`^Optional ```typescript public readonly integrationResponses: IntegrationResponse[]; ``` - *Type:* aws-cdk-lib.aws_apigateway.IntegrationResponse[] The response that API Gateway provides after a method's backend completes processing a request. API Gateway intercepts the response from the backend so that you can control how API Gateway surfaces backend responses. For example, you can map the backend status codes to codes that you define. --- ##### `passthroughBehavior`^Optional ```typescript public readonly passthroughBehavior: PassthroughBehavior; ``` - *Type:* aws-cdk-lib.aws_apigateway.PassthroughBehavior Specifies the pass-through behavior for incoming requests based on the Content-Type header in the request, and the available mapping templates specified as the requestTemplates property on the Integration resource. There are three valid values: WHEN_NO_MATCH, WHEN_NO_TEMPLATES, and NEVER. --- ##### `requestParameters`^Optional ```typescript public readonly requestParameters: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} The request parameters that API Gateway sends with the backend request. Specify request parameters as key-value pairs (string-to-string mappings), with a destination as the key and a source as the value. Specify the destination by using the following pattern integration.request.location.name, where location is querystring, path, or header, and name is a valid, unique parameter name. The source must be an existing method request parameter or a static value. You must enclose static values in single quotation marks and pre-encode these values based on their destination in the request. --- ##### `requestTemplates`^Optional ```typescript public readonly requestTemplates: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} A map of Apache Velocity templates that are applied on the request payload. The template that API Gateway uses is based on the value of the Content-Type header that's sent by the client. The content type value is the key, and the template is the value (specified as a string), such as the following snippet: ``` { "application/json": "{ \"statusCode\": 200 }" } ``` > [http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html) --- ##### `timeout`^Optional ```typescript public readonly timeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.seconds(29) The maximum amount of time an integration will run before it returns without a response. By default, the value must be between 50 milliseconds and 29 seconds. The upper bound can be increased for regional and private Rest APIs only, via a quota increase request for your acccount. This increase might require a reduction in your account-level throttle quota limit. See {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html Amazon API Gateway quotas} for more details. --- ##### `vpcLink`^Optional ```typescript public readonly vpcLink: IVpcLink; ``` - *Type:* aws-cdk-lib.aws_apigateway.IVpcLink The VpcLink used for the integration. Required if connectionType is VPC_LINK --- ##### `allowTestInvoke`^Optional ```typescript public readonly allowTestInvoke: boolean; ``` - *Type:* boolean - *Default:* true Allow invoking method from AWS Console UI (for testing purposes). This will add another permission to the AWS Lambda resource policy which will allow the `test-invoke-stage` stage to invoke this handler. If this is set to `false`, the function will only be usable from the deployment endpoint. --- ##### `proxy`^Optional ```typescript public readonly proxy: boolean; ``` - *Type:* boolean - *Default:* true Use proxy integration or normal (request/response mapping) integration. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format) --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ### LicenseObject The license information for the exposed API. #### Initializer ```typescript import { LicenseObject } from '@alma-cdk/openapix' const licenseObject: LicenseObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | The license name used for the API. | | url | string | A URL to the license used for the API. | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The license name used for the API. --- ##### `url`^Optional ```typescript public readonly url: string; ``` - *Type:* string A URL to the license used for the API. MUST be in the format of a URL. --- ### LinkObject The Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation. #### Initializer ```typescript import { LinkObject } from '@alma-cdk/openapix' const linkObject: LinkObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | A description of the link. | | operationId | string | The name of an existing, resolvable OAS operation, as defined with a unique operationId. | | operationRef | string | A relative or absolute URI reference to an OAS operation. | | parameters | {[ key: string ]: any} | A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. | | requestBody | any | A literal value or {expression} to use as a request body when calling the target operation. | | server | ServerObject | A server object to be used by the target operation. | --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A description of the link. CommonMark syntax MAY be used for rich text representation. --- ##### `operationId`^Optional ```typescript public readonly operationId: string; ``` - *Type:* string The name of an existing, resolvable OAS operation, as defined with a unique operationId. This field is mutually exclusive of the operationRef field. --- ##### `operationRef`^Optional ```typescript public readonly operationRef: string; ``` - *Type:* string A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the operationId field, and MUST point to an Operation Object. Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition. --- ##### `parameters`^Optional ```typescript public readonly parameters: {[ key: string ]: any}; ``` - *Type:* {[ key: string ]: any} A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id). --- ##### `requestBody`^Optional ```typescript public readonly requestBody: any; ``` - *Type:* any A literal value or {expression} to use as a request body when calling the target operation. --- ##### `server`^Optional ```typescript public readonly server: ServerObject; ``` - *Type:* ServerObject A server object to be used by the target operation. --- ### MediaTypeObject Each Media Type Object provides schema and examples for the media type identified by its key. #### Initializer ```typescript import { MediaTypeObject } from '@alma-cdk/openapix' const mediaTypeObject: MediaTypeObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | encoding | {[ key: string ]: EncodingObject} | A map between a property name and its encoding information. | | example | any | Example of the media type. | | examples | {[ key: string ]: ReferenceObject \| ExampleObject} | Examples of the media type. | | schema | ReferenceObject \| SchemaObject | The schema defining the content of the request, response, or parameter. | --- ##### `encoding`^Optional ```typescript public readonly encoding: {[ key: string ]: EncodingObject}; ``` - *Type:* {[ key: string ]: EncodingObject} A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded. --- ##### `example`^Optional ```typescript public readonly example: any; ``` - *Type:* any Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The example field is mutually exclusive of the examples field. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. --- ##### `examples`^Optional ```typescript public readonly examples: {[ key: string ]: ReferenceObject | ExampleObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | ExampleObject} Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema. --- ##### `schema`^Optional ```typescript public readonly schema: ReferenceObject | SchemaObject; ``` - *Type:* ReferenceObject | SchemaObject The schema defining the content of the request, response, or parameter. --- ### MockIntegrationProps #### Initializer ```typescript import { MockIntegrationProps } from '@alma-cdk/openapix' const mockIntegrationProps: MockIntegrationProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | cacheKeyParameters | string[] | A list of request parameters whose values are to be cached. | | cacheNamespace | string | An API-specific tag group of related cached parameters. | | connectionType | aws-cdk-lib.aws_apigateway.ConnectionType | The type of network connection to the integration endpoint. | | contentHandling | aws-cdk-lib.aws_apigateway.ContentHandling | Specifies how to handle request payload content type conversions. | | credentialsPassthrough | boolean | Requires that the caller's identity be passed through from the request. | | credentialsRole | aws-cdk-lib.aws_iam.IRole | An IAM role that API Gateway assumes. | | integrationResponses | aws-cdk-lib.aws_apigateway.IntegrationResponse[] | The response that API Gateway provides after a method's backend completes processing a request. | | passthroughBehavior | aws-cdk-lib.aws_apigateway.PassthroughBehavior | Specifies the pass-through behavior for incoming requests based on the Content-Type header in the request, and the available mapping templates specified as the requestTemplates property on the Integration resource. | | requestParameters | {[ key: string ]: string} | The request parameters that API Gateway sends with the backend request. | | requestTemplates | {[ key: string ]: string} | A map of Apache Velocity templates that are applied on the request payload. | | timeout | aws-cdk-lib.Duration | The maximum amount of time an integration will run before it returns without a response. | | vpcLink | aws-cdk-lib.aws_apigateway.IVpcLink | The VpcLink used for the integration. | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | --- ##### `cacheKeyParameters`^Optional ```typescript public readonly cacheKeyParameters: string[]; ``` - *Type:* string[] A list of request parameters whose values are to be cached. It determines request parameters that will make it into the cache key. --- ##### `cacheNamespace`^Optional ```typescript public readonly cacheNamespace: string; ``` - *Type:* string An API-specific tag group of related cached parameters. --- ##### `connectionType`^Optional ```typescript public readonly connectionType: ConnectionType; ``` - *Type:* aws-cdk-lib.aws_apigateway.ConnectionType - *Default:* ConnectionType.VPC_LINK if `vpcLink` property is configured; ConnectionType.Internet otherwise. The type of network connection to the integration endpoint. --- ##### `contentHandling`^Optional ```typescript public readonly contentHandling: ContentHandling; ``` - *Type:* aws-cdk-lib.aws_apigateway.ContentHandling - *Default:* none if this property isn't defined, the request payload is passed through from the method request to the integration request without modification, provided that the `passthroughBehaviors` property is configured to support payload pass-through. Specifies how to handle request payload content type conversions. --- ##### `credentialsPassthrough`^Optional ```typescript public readonly credentialsPassthrough: boolean; ``` - *Type:* boolean - *Default:* Caller identity is not passed through Requires that the caller's identity be passed through from the request. --- ##### `credentialsRole`^Optional ```typescript public readonly credentialsRole: IRole; ``` - *Type:* aws-cdk-lib.aws_iam.IRole - *Default:* A role is not assumed An IAM role that API Gateway assumes. Mutually exclusive with `credentialsPassThrough`. --- ##### `integrationResponses`^Optional ```typescript public readonly integrationResponses: IntegrationResponse[]; ``` - *Type:* aws-cdk-lib.aws_apigateway.IntegrationResponse[] The response that API Gateway provides after a method's backend completes processing a request. API Gateway intercepts the response from the backend so that you can control how API Gateway surfaces backend responses. For example, you can map the backend status codes to codes that you define. --- ##### `passthroughBehavior`^Optional ```typescript public readonly passthroughBehavior: PassthroughBehavior; ``` - *Type:* aws-cdk-lib.aws_apigateway.PassthroughBehavior Specifies the pass-through behavior for incoming requests based on the Content-Type header in the request, and the available mapping templates specified as the requestTemplates property on the Integration resource. There are three valid values: WHEN_NO_MATCH, WHEN_NO_TEMPLATES, and NEVER. --- ##### `requestParameters`^Optional ```typescript public readonly requestParameters: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} The request parameters that API Gateway sends with the backend request. Specify request parameters as key-value pairs (string-to-string mappings), with a destination as the key and a source as the value. Specify the destination by using the following pattern integration.request.location.name, where location is querystring, path, or header, and name is a valid, unique parameter name. The source must be an existing method request parameter or a static value. You must enclose static values in single quotation marks and pre-encode these values based on their destination in the request. --- ##### `requestTemplates`^Optional ```typescript public readonly requestTemplates: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} A map of Apache Velocity templates that are applied on the request payload. The template that API Gateway uses is based on the value of the Content-Type header that's sent by the client. The content type value is the key, and the template is the value (specified as a string), such as the following snippet: ``` { "application/json": "{ \"statusCode\": 200 }" } ``` > [http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html) --- ##### `timeout`^Optional ```typescript public readonly timeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.seconds(29) The maximum amount of time an integration will run before it returns without a response. By default, the value must be between 50 milliseconds and 29 seconds. The upper bound can be increased for regional and private Rest APIs only, via a quota increase request for your acccount. This increase might require a reduction in your account-level throttle quota limit. See {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html Amazon API Gateway quotas} for more details. --- ##### `vpcLink`^Optional ```typescript public readonly vpcLink: IVpcLink; ``` - *Type:* aws-cdk-lib.aws_apigateway.IVpcLink The VpcLink used for the integration. Required if connectionType is VPC_LINK --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ### OAuthFlowObject Configuration details for a supported OAuth Flow. #### Initializer ```typescript import { OAuthFlowObject } from '@alma-cdk/openapix' const oAuthFlowObject: OAuthFlowObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | scopes | {[ key: string ]: string} | The available scopes for the OAuth2 security scheme. | | authorizationUrl | string | The authorization URL to be used for this flow. | | refreshUrl | string | The URL to be used for obtaining refresh tokens. | | tokenUrl | string | The token URL to be used for this flow. | --- ##### `scopes`^Required ```typescript public readonly scopes: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. --- ##### `authorizationUrl`^Optional ```typescript public readonly authorizationUrl: string; ``` - *Type:* string The authorization URL to be used for this flow. This MUST be in the form of a URL. REQUIRED for oauth2 ("implicit", "authorizationCode"). --- ##### `refreshUrl`^Optional ```typescript public readonly refreshUrl: string; ``` - *Type:* string The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. --- ##### `tokenUrl`^Optional ```typescript public readonly tokenUrl: string; ``` - *Type:* string The token URL to be used for this flow. This MUST be in the form of a URL. REQUIRED for oauth2 ("password", "clientCredentials", "authorizationCode"). --- ### OAuthFlowsObject Allows configuration of the supported OAuth Flows. #### Initializer ```typescript import { OAuthFlowsObject } from '@alma-cdk/openapix' const oAuthFlowsObject: OAuthFlowsObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | authorizationCode | OAuthFlowObject | Configuration for the OAuth Authorization Code flow. | | clientCredentials | OAuthFlowObject | Configuration for the OAuth Client Credentials flow. | | implicit | OAuthFlowObject | Configuration for the OAuth Implicit flow. | | password | OAuthFlowObject | Configuration for the OAuth Resource Owner Password flow. | --- ##### `authorizationCode`^Optional ```typescript public readonly authorizationCode: OAuthFlowObject; ``` - *Type:* OAuthFlowObject Configuration for the OAuth Authorization Code flow. Previously called accessCode in OpenAPI 2.0. --- ##### `clientCredentials`^Optional ```typescript public readonly clientCredentials: OAuthFlowObject; ``` - *Type:* OAuthFlowObject Configuration for the OAuth Client Credentials flow. Previously called application in OpenAPI 2.0. --- ##### `implicit`^Optional ```typescript public readonly implicit: OAuthFlowObject; ``` - *Type:* OAuthFlowObject Configuration for the OAuth Implicit flow. --- ##### `password`^Optional ```typescript public readonly password: OAuthFlowObject; ``` - *Type:* OAuthFlowObject Configuration for the OAuth Resource Owner Password flow. --- ### OperationObject Describes a single API operation on a path. #### Initializer ```typescript import { OperationObject } from '@alma-cdk/openapix' const operationObject: OperationObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | responses | ResponsesObject | The list of possible responses as they are returned from executing this operation. | | callbacks | {[ key: string ]: ReferenceObject \| CallbackObject} | A map of possible out-of band callbacks related to the parent operation. | | deprecated | boolean | Declares this operation to be deprecated. | | description | string | A verbose explanation of the operation behavior. | | externalDocs | ExternalDocumentationObject | Additional external documentation for this operation. | | operationId | string | Unique string used to identify the operation. | | parameters | ReferenceObject \| ParameterObject[] | A list of parameters that are applicable for this operation. | | requestBody | ReferenceObject \| RequestBodyObject | The request body applicable for this operation. | | security | SecurityRequirementObject[] | A declaration of which security mechanisms can be used for this operation. | | summary | string | A short summary of what the operation does. | | tags | string[] | A list of tags for API documentation control. | --- ##### `responses`^Required ```typescript public readonly responses: ResponsesObject; ``` - *Type:* ResponsesObject The list of possible responses as they are returned from executing this operation. --- ##### `callbacks`^Optional ```typescript public readonly callbacks: {[ key: string ]: ReferenceObject | CallbackObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | CallbackObject} A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: ExternalDocumentationObject; ``` - *Type:* ExternalDocumentationObject Additional external documentation for this operation. --- ##### `operationId`^Optional ```typescript public readonly operationId: string; ``` - *Type:* string Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. --- ##### `parameters`^Optional ```typescript public readonly parameters: (ReferenceObject | ParameterObject)[]; ``` - *Type:* ReferenceObject | ParameterObject[] A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters. --- ##### `requestBody`^Optional ```typescript public readonly requestBody: ReferenceObject | RequestBodyObject; ``` - *Type:* ReferenceObject | RequestBodyObject The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers. --- ##### `security`^Optional ```typescript public readonly security: SecurityRequirementObject[]; ``` - *Type:* SecurityRequirementObject[] A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement ({}) can be included in the array. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string A short summary of what the operation does. --- ##### `tags`^Optional ```typescript public readonly tags: string[]; ``` - *Type:* string[] A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. --- ### ParameterObject Describes a single operation parameter. A unique parameter is defined by a combination of a name and location. #### Initializer ```typescript import { ParameterObject } from '@alma-cdk/openapix' const parameterObject: ParameterObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | in | string | The location of the parameter. | | name | string | The name of the parameter. Parameter names are case sensitive. | | allowEmptyValue | boolean | Sets the ability to pass empty-valued parameters. | | deprecated | boolean | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. | | description | string | A brief description of the parameter. | | required | boolean | Determines whether this parameter is mandatory. | --- ##### `in`^Required ```typescript public readonly in: string; ``` - *Type:* string The location of the parameter. Possible values are "query", "header", "path" or "cookie". --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The name of the parameter. Parameter names are case sensitive. If in is "path", the name field MUST correspond to a template expression occurring within the path field in the Paths Object. See Path Templating for further information. If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored. For all other cases, the name corresponds to the parameter name used by the in property. --- ##### `allowEmptyValue`^Optional ```typescript public readonly allowEmptyValue: boolean; ``` - *Type:* boolean Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. --- ### PathItemObject Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. #### Initializer ```typescript import { PathItemObject } from '@alma-cdk/openapix' const pathItemObject: PathItemObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | delete | OperationObject | A definition of a DELETE operation on this path. | | description | string | An optional, string description, intended to apply to all operations in this path. | | get | OperationObject | A definition of a GET operation on this path. | | head | OperationObject | A definition of a HEAD operation on this path. | | options | OperationObject | A definition of a OPTIONS operation on this path. | | parameters | ReferenceObject \| ParameterObject[] | A list of parameters that are applicable for all the operations described under this path. | | patch | OperationObject | A definition of a PATCH operation on this path. | | post | OperationObject | A definition of a POST operation on this path. | | put | OperationObject | A definition of a PUT operation on this path. | | summary | string | An optional, string summary, intended to apply to all operations in this path. | | trace | OperationObject | A definition of a TRACE operation on this path. | --- ##### `delete`^Optional ```typescript public readonly delete: OperationObject; ``` - *Type:* OperationObject A definition of a DELETE operation on this path. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation. --- ##### `get`^Optional ```typescript public readonly get: OperationObject; ``` - *Type:* OperationObject A definition of a GET operation on this path. --- ##### `head`^Optional ```typescript public readonly head: OperationObject; ``` - *Type:* OperationObject A definition of a HEAD operation on this path. --- ##### `options`^Optional ```typescript public readonly options: OperationObject; ``` - *Type:* OperationObject A definition of a OPTIONS operation on this path. --- ##### `parameters`^Optional ```typescript public readonly parameters: (ReferenceObject | ParameterObject)[]; ``` - *Type:* ReferenceObject | ParameterObject[] A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters. --- ##### `patch`^Optional ```typescript public readonly patch: OperationObject; ``` - *Type:* OperationObject A definition of a PATCH operation on this path. --- ##### `post`^Optional ```typescript public readonly post: OperationObject; ``` - *Type:* OperationObject A definition of a POST operation on this path. --- ##### `put`^Optional ```typescript public readonly put: OperationObject; ``` - *Type:* OperationObject A definition of a PUT operation on this path. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string An optional, string summary, intended to apply to all operations in this path. --- ##### `trace`^Optional ```typescript public readonly trace: OperationObject; ``` - *Type:* OperationObject A definition of a TRACE operation on this path. --- ### Paths Paths with methods containing integrations. #### Initializer ```typescript import { Paths } from '@alma-cdk/openapix' const paths: Paths = { ... } ``` ### PathsObject Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to ACL constraints. #### Initializer ```typescript import { PathsObject } from '@alma-cdk/openapix' const pathsObject: PathsObject = { ... } ``` ### ReferenceObject A simple object to allow referencing other components in the specification, internally and externally. #### Initializer ```typescript import { ReferenceObject } from '@alma-cdk/openapix' const referenceObject: ReferenceObject = { ... } ``` ### RequestBodyObject Describes a single request body. #### Initializer ```typescript import { RequestBodyObject } from '@alma-cdk/openapix' const requestBodyObject: RequestBodyObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | content | {[ key: string ]: MediaTypeObject} | The content of the request body. | | description | string | A brief description of the request body. | | required | boolean | Determines if the request body is required in the request. | --- ##### `content`^Required ```typescript public readonly content: {[ key: string ]: MediaTypeObject}; ``` - *Type:* {[ key: string ]: MediaTypeObject} The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines if the request body is required in the request. Defaults to false. --- ### ResponseObject Describes a single response from an API Operation, including design-time, static links to operations based on the response. #### Initializer ```typescript import { ResponseObject } from '@alma-cdk/openapix' const responseObject: ResponseObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | A short description of the response. | | content | {[ key: string ]: ReferenceObject \| MediaTypeObject} | A map containing descriptions of potential response payloads. | | headers | {[ key: string ]: ReferenceObject \| HeaderObject} | Maps a header name to its definition. | | links | {[ key: string ]: ReferenceObject \| LinkObject} | A map of operations links that can be followed from the response. | --- ##### `description`^Required ```typescript public readonly description: string; ``` - *Type:* string A short description of the response. CommonMark syntax MAY be used for rich text representation. --- ##### `content`^Optional ```typescript public readonly content: {[ key: string ]: ReferenceObject | MediaTypeObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | MediaTypeObject} A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: ReferenceObject | HeaderObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | HeaderObject} Maps a header name to its definition. RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored. --- ##### `links`^Optional ```typescript public readonly links: {[ key: string ]: ReferenceObject | LinkObject}; ``` - *Type:* {[ key: string ]: ReferenceObject | LinkObject} A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects. --- ### ResponsesObject A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The default MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call. #### Initializer ```typescript import { ResponsesObject } from '@alma-cdk/openapix' const responsesObject: ResponsesObject = { ... } ``` ### SchemaObject The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00. For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema. #### Initializer ```typescript import { SchemaObject } from '@alma-cdk/openapix' const schemaObject: SchemaObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | deprecated | boolean | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. | | discriminator | DiscriminatorObject | Adds support for polymorphism. | | example | any | A free-form property to include an example of an instance for this schema. | | externalDocs | ExternalDocumentationObject | Additional external documentation for this schema. | | nullable | boolean | A true value adds "null" to the allowed type specified by the type keyword, only if type is explicitly defined within the same Schema Object. | | readOnly | boolean | Relevant only for Schema "properties" definitions. | | writeOnly | boolean | Relevant only for Schema "properties" definitions. | | xml | XmlObject | This MAY be used only on properties schemas. | --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `discriminator`^Optional ```typescript public readonly discriminator: DiscriminatorObject; ``` - *Type:* DiscriminatorObject Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details. --- ##### `example`^Optional ```typescript public readonly example: any; ``` - *Type:* any A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: ExternalDocumentationObject; ``` - *Type:* ExternalDocumentationObject Additional external documentation for this schema. --- ##### `nullable`^Optional ```typescript public readonly nullable: boolean; ``` - *Type:* boolean A true value adds "null" to the allowed type specified by the type keyword, only if type is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of null as a value. A false value leaves the specified or default type unmodified. The default value is false. --- ##### `readOnly`^Optional ```typescript public readonly readOnly: boolean; ``` - *Type:* boolean Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false. --- ##### `writeOnly`^Optional ```typescript public readonly writeOnly: boolean; ``` - *Type:* boolean Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false. --- ##### `xml`^Optional ```typescript public readonly xml: XmlObject; ``` - *Type:* XmlObject This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. --- ### SchemaProps Props given to `new Schema`. Essentially an OpenApi v3 "source" without `x-amazon-apigateway-` extensions. #### Initializer ```typescript import { SchemaProps } from '@alma-cdk/openapix' const schemaProps: SchemaProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | info | InfoObject | Provides metadata about the API. | | openapi | string | This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. | | paths | PathsObject | The available paths and operations for the API. | | components | ComponentsObject | An element to hold various schemas for the specification. | | externalDocs | ExternalDocumentationObject | Additional external documentation. | | security | SecurityRequirementObject[] | A declaration of which security mechanisms can be used across the API. | | servers | ServerObject[] | An array of Server Objects, which provide connectivity information to a target server. | | tags | TagObject[] | A list of tags used by the specification with additional metadata. | --- ##### `info`^Required ```typescript public readonly info: InfoObject; ``` - *Type:* InfoObject Provides metadata about the API. The metadata MAY be used by tooling as required. --- *Example* ```typescript { title: "FancyPants API", version: "1.23.105", } ``` ##### `openapi`^Required ```typescript public readonly openapi: string; ``` - *Type:* string This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string. --- *Example* ```typescript '3.0.0' ``` ##### `paths`^Required ```typescript public readonly paths: PathsObject; ``` - *Type:* PathsObject The available paths and operations for the API. --- ##### `components`^Optional ```typescript public readonly components: ComponentsObject; ``` - *Type:* ComponentsObject An element to hold various schemas for the specification. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: ExternalDocumentationObject; ``` - *Type:* ExternalDocumentationObject Additional external documentation. --- ##### `security`^Optional ```typescript public readonly security: SecurityRequirementObject[]; ``` - *Type:* SecurityRequirementObject[] A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array. --- ##### `servers`^Optional ```typescript public readonly servers: ServerObject[]; ``` - *Type:* ServerObject[] An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /. --- ##### `tags`^Optional ```typescript public readonly tags: TagObject[]; ``` - *Type:* TagObject[] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. --- ### SecurityRequirementObject Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object, only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request. #### Initializer ```typescript import { SecurityRequirementObject } from '@alma-cdk/openapix' const securityRequirementObject: SecurityRequirementObject = { ... } ``` ### SecuritySchemeObject Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery. #### Initializer ```typescript import { SecuritySchemeObject } from '@alma-cdk/openapix' const securitySchemeObject: SecuritySchemeObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | string | The type of the security scheme. | | bearerFormat | string | A hint to the client to identify how the bearer token is formatted. | | description | string | A short description for security scheme. | | flow | OAuthFlowsObject | An object containing configuration information for the flow types supported. | | in | string | The location of the API key. | | name | string | The name of the header, query or cookie parameter to be used. | | openIdConnectUrl | string | OpenId Connect URL to discover OAuth2 configuration values. | | scheme | string | The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. | --- ##### `type`^Required ```typescript public readonly type: string; ``` - *Type:* string The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect". --- ##### `bearerFormat`^Optional ```typescript public readonly bearerFormat: string; ``` - *Type:* string A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description for security scheme. CommonMark syntax MAY be used for rich text representation. --- ##### `flow`^Optional ```typescript public readonly flow: OAuthFlowsObject; ``` - *Type:* OAuthFlowsObject An object containing configuration information for the flow types supported. REQUIRED for oauth2. --- ##### `in`^Optional ```typescript public readonly in: string; ``` - *Type:* string The location of the API key. Valid values are "query", "header" or "cookie". REQUIRED for apiKey. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string The name of the header, query or cookie parameter to be used. REQUIRED for apiKey. --- ##### `openIdConnectUrl`^Optional ```typescript public readonly openIdConnectUrl: string; ``` - *Type:* string OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. REQUIRED for openIdConnect. --- ##### `scheme`^Optional ```typescript public readonly scheme: string; ``` - *Type:* string The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry. REQUIRED for http. --- ### ServerObject An object representing a Server. #### Initializer ```typescript import { ServerObject } from '@alma-cdk/openapix' const serverObject: ServerObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | url | string | REQUIRED. | | description | string | An optional string describing the host designated by the URL. | | variables | {[ key: string ]: ServerVariableObject} | A map between a variable name and its value. | --- ##### `url`^Required ```typescript public readonly url: string; ``` - *Type:* string REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation. --- ##### `variables`^Optional ```typescript public readonly variables: {[ key: string ]: ServerVariableObject}; ``` - *Type:* {[ key: string ]: ServerVariableObject} A map between a variable name and its value. The value is used for substitution in the server's URL template. --- ### ServerVariableObject An object representing a Server Variable for server URL template substitution. #### Initializer ```typescript import { ServerVariableObject } from '@alma-cdk/openapix' const serverVariableObject: ServerVariableObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | default | string | The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. | | description | string | An optional description for the server variable. | | enum | string[] | An enumeration of string values to be used if the substitution options are from a limited set. | --- ##### `default`^Required ```typescript public readonly default: string; ``` - *Type:* string The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object's treatment of default values, because in those cases parameter values are optional. If the enum is defined, the value SHOULD exist in the enum's values. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional description for the server variable. CommonMark syntax MAY be used for rich text representation. --- ##### `enum`^Optional ```typescript public readonly enum: string[]; ``` - *Type:* string[] An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. --- ### TagObject Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. #### Initializer ```typescript import { TagObject } from '@alma-cdk/openapix' const tagObject: TagObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | The name of the tag. | | description | string | A short description for the tag. | | externalDocs | ExternalDocumentationObject | Additional external documentation for this tag. | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The name of the tag. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description for the tag. CommonMark syntax MAY be used for rich text representation. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: ExternalDocumentationObject; ``` - *Type:* ExternalDocumentationObject Additional external documentation for this tag. --- ### Validator Validator configuration. #### Initializer ```typescript import { Validator } from '@alma-cdk/openapix' const validator: Validator = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | validateRequestBody | boolean | *No description.* | | validateRequestParameters | boolean | *No description.* | | default | boolean | *No description.* | --- ##### `validateRequestBody`^Required ```typescript public readonly validateRequestBody: boolean; ``` - *Type:* boolean --- ##### `validateRequestParameters`^Required ```typescript public readonly validateRequestParameters: boolean; ``` - *Type:* boolean --- ##### `default`^Optional ```typescript public readonly default: boolean; ``` - *Type:* boolean --- ### ValidatorConfig Method integration validator configuration. #### Initializer ```typescript import { ValidatorConfig } from '@alma-cdk/openapix' const validatorConfig: ValidatorConfig = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | validator | string | Validator identifier for method integration. This will override the default validator if one configured. | --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string Validator identifier for method integration. This will override the default validator if one configured. Should match a key from OpenApi schema `components.securitySchemas`. --- ### XAmazonApigatewayAuthorizer Describes the `x-amazon-apigateway-authorizer` value. > [https://awslabs.github.io/smithy/1.0/spec/aws/amazon-apigateway.html](https://awslabs.github.io/smithy/1.0/spec/aws/amazon-apigateway.html) #### Initializer ```typescript import { XAmazonApigatewayAuthorizer } from '@alma-cdk/openapix' const xAmazonApigatewayAuthorizer: XAmazonApigatewayAuthorizer = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | string | The type of the authorizer. This is a required property. | | authorizerCredentials | string | The credentials required for invoking the authorizer, if any, in the form of an ARN of an IAM execution role. | | authorizerResultTtlInSeconds | number | The number of seconds during which authorizer result is cached. | | authorizerUri | string | The Uniform Resource Identifier (URI) of the authorizer Lambda function. | | identitySource | string | A comma-separated list of mapping expressions of the request parameters as the identity source. | | identityValidationExpression | string | A regular expression for validating the token as the incoming identity. | | providerARNs | string[] | List of Cognito User Pool ARNs. | --- ##### `type`^Required ```typescript public readonly type: string; ``` - *Type:* string The type of the authorizer. This is a required property. For REST APIs, specify `token` for an authorizer with the caller identity embedded in an authorization token. Specify `request` for an authorizer with the caller identity contained in request parameters. --- *Example* ```typescript 'token' 'request' 'cognito_user_pools' ``` ##### `authorizerCredentials`^Optional ```typescript public readonly authorizerCredentials: string; ``` - *Type:* string The credentials required for invoking the authorizer, if any, in the form of an ARN of an IAM execution role. --- *Example* ```typescript 'arn:aws:iam::123456789012:role/MyRole' ``` ##### `authorizerResultTtlInSeconds`^Optional ```typescript public readonly authorizerResultTtlInSeconds: number; ``` - *Type:* number The number of seconds during which authorizer result is cached. --- *Example* ```typescript 60 ``` ##### `authorizerUri`^Optional ```typescript public readonly authorizerUri: string; ``` - *Type:* string The Uniform Resource Identifier (URI) of the authorizer Lambda function. --- *Example* ```typescript 'arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations' ``` ##### `identitySource`^Optional ```typescript public readonly identitySource: string; ``` - *Type:* string A comma-separated list of mapping expressions of the request parameters as the identity source. Applicable for the authorizer of the `request` and `jwt` type only. --- *Example* ```typescript 'method.request.header.Authorization' 'method.request.header.Authorization, context.identity.sourceIp' 'method.request.header.Auth, method.request.querystring.Name' ``` ##### `identityValidationExpression`^Optional ```typescript public readonly identityValidationExpression: string; ``` - *Type:* string A regular expression for validating the token as the incoming identity. --- *Example* ```typescript '^x-[a-z]+' ``` ##### `providerARNs`^Optional ```typescript public readonly providerARNs: string[]; ``` - *Type:* string[] List of Cognito User Pool ARNs. Applicable for the authorizer of the `cognito_user_pools` type only. --- *Example* ```typescript ['arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}] ``` ### XAmazonApigatewayIntegration Specifies details of the backend integration used for this method. This extension is an extended property of the OpenAPI Operation object. The result is an API Gateway integration object. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) #### Initializer ```typescript import { XAmazonApigatewayIntegration } from '@alma-cdk/openapix' const xAmazonApigatewayIntegration: XAmazonApigatewayIntegration = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | httpMethod | string | The HTTP method used in the integration request. | | type | aws-cdk-lib.aws_apigateway.IntegrationType | The type of integration with the specified backend. | | uri | string | The endpoint URI of the backend. | | cacheKeyParameters | string[] | A list of request parameters whose values are to be cached. | | cacheNamespace | string | An API-specific tag group of related cached parameters. | | connectionId | string | The ID of a VpcLink for the private integration. | | connectionType | aws-cdk-lib.aws_apigateway.ConnectionType | The integration connection type. | | contentHandling | aws-cdk-lib.aws_apigateway.ContentHandling | Response payload encoding conversion types. | | credentials | string | For AWS IAM role-based credentials, specify the ARN of an appropriate IAM role. | | passthroughBehavior | aws-cdk-lib.aws_apigateway.PassthroughBehavior | Specifies how a request payload of unmapped content type is passed through the integration request without modification. | | requestParameters | XAmazonApigatewayIntegrationRequestParameters | Specifies mappings from method request parameters to integration request parameters. | | requestTemplates | XAmazonApigatewayIntegrationRequestTemplates | Mapping templates for a request payload of specified MIME types. | | responses | XAmazonApigatewayIntegrationResponses | Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses. | | timeoutInMillis | number | Integration timeouts between 50 ms and 29,000 ms. | | tlsConfig | XAmazonApigatewayIntegrationTlsConfig | Specifies the TLS configuration for an integration. | --- ##### `httpMethod`^Required ```typescript public readonly httpMethod: string; ``` - *Type:* string - *Default:* 'POST' The HTTP method used in the integration request. For Lambda function invocations, the value must be POST. --- ##### `type`^Required ```typescript public readonly type: IntegrationType; ``` - *Type:* aws-cdk-lib.aws_apigateway.IntegrationType The type of integration with the specified backend. Valid values are: - `http` or `http_proxy`, for integration with an HTTP backend. - `aws_proxy`, for integration with AWS Lambda functions. - `aws`, for integration with AWS Lambda functions or other AWS services, such as Amazon DynamoDB, Amazon Simple Notification Service, or Amazon Simple Queue Service. - `mock`, for integration with API Gateway without invoking any backend. --- ##### `uri`^Required ```typescript public readonly uri: string; ``` - *Type:* string The endpoint URI of the backend. For integrations of the aws type, this is an ARN value. For the HTTP integration, this is the URL of the HTTP endpoint including the https or http scheme. --- ##### `cacheKeyParameters`^Optional ```typescript public readonly cacheKeyParameters: string[]; ``` - *Type:* string[] A list of request parameters whose values are to be cached. --- ##### `cacheNamespace`^Optional ```typescript public readonly cacheNamespace: string; ``` - *Type:* string An API-specific tag group of related cached parameters. --- ##### `connectionId`^Optional ```typescript public readonly connectionId: string; ``` - *Type:* string The ID of a VpcLink for the private integration. --- ##### `connectionType`^Optional ```typescript public readonly connectionType: ConnectionType; ``` - *Type:* aws-cdk-lib.aws_apigateway.ConnectionType The integration connection type. The valid value is "VPC_LINK" for private integration or "INTERNET", otherwise. --- *Example* ```typescript 'VPC_LINK' ``` ##### `contentHandling`^Optional ```typescript public readonly contentHandling: ContentHandling; ``` - *Type:* aws-cdk-lib.aws_apigateway.ContentHandling Response payload encoding conversion types. Valid values are 1) CONVERT_TO_TEXT, for converting a binary payload into a base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT_TO_BINARY, for converting a text payload into a base64-decoded blob or passing through a binary payload natively without modification. --- ##### `credentials`^Optional ```typescript public readonly credentials: string; ``` - *Type:* string For AWS IAM role-based credentials, specify the ARN of an appropriate IAM role. If unspecified, credentials default to resource-based permissions that must be added manually to allow the API to access the resource. For more information, see Granting Permissions Using a Resource Policy. Note: When using IAM credentials, make sure that AWS STS Regional endpoints are enabled for the Region where this API is deployed for best performance. > [https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy) --- ##### `passthroughBehavior`^Optional ```typescript public readonly passthroughBehavior: PassthroughBehavior; ``` - *Type:* aws-cdk-lib.aws_apigateway.PassthroughBehavior Specifies how a request payload of unmapped content type is passed through the integration request without modification. Supported values are when_no_templates, when_no_match, and never --- ##### `requestParameters`^Optional ```typescript public readonly requestParameters: XAmazonApigatewayIntegrationRequestParameters; ``` - *Type:* XAmazonApigatewayIntegrationRequestParameters Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body. --- ##### `requestTemplates`^Optional ```typescript public readonly requestTemplates: XAmazonApigatewayIntegrationRequestTemplates; ``` - *Type:* XAmazonApigatewayIntegrationRequestTemplates Mapping templates for a request payload of specified MIME types. --- ##### `responses`^Optional ```typescript public readonly responses: XAmazonApigatewayIntegrationResponses; ``` - *Type:* XAmazonApigatewayIntegrationResponses Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses. --- ##### `timeoutInMillis`^Optional ```typescript public readonly timeoutInMillis: number; ``` - *Type:* number Integration timeouts between 50 ms and 29,000 ms. --- *Example* ```typescript 1000 ``` ##### `tlsConfig`^Optional ```typescript public readonly tlsConfig: XAmazonApigatewayIntegrationTlsConfig; ``` - *Type:* XAmazonApigatewayIntegrationTlsConfig Specifies the TLS configuration for an integration. --- ### XAmazonApigatewayIntegrationRequestParameters Specifies mappings from named method request parameters to integration request parameters. The method request parameters must be defined before being referenced. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestParameters.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestParameters.html) #### Initializer ```typescript import { XAmazonApigatewayIntegrationRequestParameters } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationRequestParameters: XAmazonApigatewayIntegrationRequestParameters = { ... } ``` ### XAmazonApigatewayIntegrationRequestTemplates Specifies mapping templates for a request payload of the specified MIME types. #### Initializer ```typescript import { XAmazonApigatewayIntegrationRequestTemplates } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationRequestTemplates: XAmazonApigatewayIntegrationRequestTemplates = { ... } ``` ### XAmazonApigatewayIntegrationResponse Defines a response and specifies parameter mappings or payload mappings from the integration response to the method response. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-response.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-response.html) #### Initializer ```typescript import { XAmazonApigatewayIntegrationResponse } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationResponse: XAmazonApigatewayIntegrationResponse = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | statusCode | string | HTTP status code for the method response. | | contentHandling | aws-cdk-lib.aws_apigateway.ContentHandling | Response payload encoding conversion types. | | responseParameters | XAmazonApigatewayIntegrationResponseParameters | Specifies parameter mappings for the response. | | responseTemplates | XAmazonApigatewayIntegrationResponseTemplates | Specifies MIME type-specific mapping templates for the response’s payload. | --- ##### `statusCode`^Required ```typescript public readonly statusCode: string; ``` - *Type:* string HTTP status code for the method response. This must correspond to a matching response in the OpenAPI Operation responses field. --- *Example* ```typescript '200' ``` ##### `contentHandling`^Optional ```typescript public readonly contentHandling: ContentHandling; ``` - *Type:* aws-cdk-lib.aws_apigateway.ContentHandling Response payload encoding conversion types. Valid values are 1) CONVERT_TO_TEXT, for converting a binary payload into a base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT_TO_BINARY, for converting a text payload into a base64-decoded blob or passing through a binary payload natively without modification. --- ##### `responseParameters`^Optional ```typescript public readonly responseParameters: XAmazonApigatewayIntegrationResponseParameters; ``` - *Type:* XAmazonApigatewayIntegrationResponseParameters Specifies parameter mappings for the response. Only the header and body parameters of the integration response can be mapped to the header parameters of the method. --- ##### `responseTemplates`^Optional ```typescript public readonly responseTemplates: XAmazonApigatewayIntegrationResponseTemplates; ``` - *Type:* XAmazonApigatewayIntegrationResponseTemplates Specifies MIME type-specific mapping templates for the response’s payload. --- *Example* ```typescript { 'application/json': '#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }', } ``` ### XAmazonApigatewayIntegrationResponseParameters Specifies mappings from integration method response parameters to method response parameters. You can map header, body, or static values to the header type of the method response. *Example* ```typescript { 'method.response.header.Location' : 'integration.response.body.redirect.url', 'method.response.header.x-user-id' : 'integration.response.header.x-userid' } ``` #### Initializer ```typescript import { XAmazonApigatewayIntegrationResponseParameters } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationResponseParameters: XAmazonApigatewayIntegrationResponseParameters = { ... } ``` ### XAmazonApigatewayIntegrationResponses Defines the method's responses and specifies parameter mappings or payload mappings from integration responses to method responses. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-responses.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-responses.html) #### Initializer ```typescript import { XAmazonApigatewayIntegrationResponses } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationResponses: XAmazonApigatewayIntegrationResponses = { ... } ``` ### XAmazonApigatewayIntegrationResponseTemplates Specifies a mapping template to transform the integration response body to the method response body for a given MIME type. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html#models-mappings-mappings](https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html#models-mappings-mappings) *Example* ```typescript { 'application/json': '#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }', } ``` #### Initializer ```typescript import { XAmazonApigatewayIntegrationResponseTemplates } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationResponseTemplates: XAmazonApigatewayIntegrationResponseTemplates = { ... } ``` ### XAmazonApigatewayIntegrationTlsConfig Specifies the TLS configuration for an integration. #### Initializer ```typescript import { XAmazonApigatewayIntegrationTlsConfig } from '@alma-cdk/openapix' const xAmazonApigatewayIntegrationTlsConfig: XAmazonApigatewayIntegrationTlsConfig = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | insecureSkipVerification | boolean | Specifies whether or not API Gateway skips verification that the certificate for an integration endpoint is issued by a supported c ertificate authority. | --- ##### `insecureSkipVerification`^Required ```typescript public readonly insecureSkipVerification: boolean; ``` - *Type:* boolean Specifies whether or not API Gateway skips verification that the certificate for an integration endpoint is issued by a supported c ertificate authority. This isn’t recommended, but it enables you to use certificates that are signed by private certificate authorities, or certificates that are self-signed. If enabled, API Gateway still performs basic certificate validation, which includes checking the certificate's expiration date, hostname, and presence of a root certificate authority. Supported only for HTTP and HTTP_PROXY integrations. --- ### XAmazonApigatewayRequestValidator Request validator configuration. > [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-request-validators.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-request-validators.html) #### Initializer ```typescript import { XAmazonApigatewayRequestValidator } from '@alma-cdk/openapix' const xAmazonApigatewayRequestValidator: XAmazonApigatewayRequestValidator = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | validateRequestBody | boolean | *No description.* | | validateRequestParameters | boolean | *No description.* | --- ##### `validateRequestBody`^Required ```typescript public readonly validateRequestBody: boolean; ``` - *Type:* boolean --- ##### `validateRequestParameters`^Required ```typescript public readonly validateRequestParameters: boolean; ``` - *Type:* boolean --- ### XmlObject A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are not inferred (for singular/plural forms) and the name property SHOULD be used to add that information. See examples for expected behavior. #### Initializer ```typescript import { XmlObject } from '@alma-cdk/openapix' const xmlObject: XmlObject = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | attribute | boolean | Declares whether the property definition translates to an attribute instead of an element. | | name | string | Replaces the name of the element/attribute used for the described schema property. | | namespace | string | The URI of the namespace definition. | | prefix | string | The prefix to be used for the name. | | wrapped | boolean | MAY be used only for an array definition. | --- ##### `attribute`^Optional ```typescript public readonly attribute: boolean; ``` - *Type:* boolean Declares whether the property definition translates to an attribute instead of an element. Default value is false. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string Replaces the name of the element/attribute used for the described schema property. When defined within items, it will affect the name of the individual XML elements within the list. When defined alongside type being array (outside the items), it will affect the wrapping element and only if wrapped is true. If wrapped is false, it will be ignored. --- ##### `namespace`^Optional ```typescript public readonly namespace: string; ``` - *Type:* string The URI of the namespace definition. Value MUST be in the form of an absolute URI. --- ##### `prefix`^Optional ```typescript public readonly prefix: string; ``` - *Type:* string The prefix to be used for the name. --- ##### `wrapped`^Optional ```typescript public readonly wrapped: boolean; ``` - *Type:* boolean MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ) or unwrapped (). Default value is false. The definition takes effect only when defined alongside type being array (outside the items). --- ## Classes ### AwsIntegration Defines direct AWS service integration. #### Initializers ```typescript import { AwsIntegration } from '@alma-cdk/openapix' new AwsIntegration(scope: Construct, props: AwsIntegrationProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | props | AwsIntegrationProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `props`^Required - *Type:* AwsIntegrationProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### CorsHeaders #### Initializers ```typescript import { CorsHeaders } from '@alma-cdk/openapix' new CorsHeaders() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | from | *No description.* | --- ##### `from` ```typescript import { CorsHeaders } from '@alma-cdk/openapix' CorsHeaders.from(scope: Construct, values: ...string[]) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `values`^Required - *Type:* ...string[] --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | ANY | string | *No description.* | --- ##### `ANY`^Required ```typescript public readonly ANY: string; ``` - *Type:* string --- ### CorsIntegration Defines `OPTIONS` integration used in Cross-Origin Resource Sharing (CORS). > [https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#mapping-response-parameters](https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#mapping-response-parameters) #### Initializers ```typescript import { CorsIntegration } from '@alma-cdk/openapix' new CorsIntegration(_: Construct, props: CorsIntegrationProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | _ | constructs.Construct | *No description.* | | props | CorsIntegrationProps | *No description.* | --- ##### `_`^Required - *Type:* constructs.Construct --- ##### `props`^Required - *Type:* CorsIntegrationProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### CorsMethods #### Initializers ```typescript import { CorsMethods } from '@alma-cdk/openapix' new CorsMethods() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | from | *No description.* | --- ##### `from` ```typescript import { CorsMethods } from '@alma-cdk/openapix' CorsMethods.from(scope: Construct, values: ...string[]) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `values`^Required - *Type:* ...string[] --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | ANY | string | *No description.* | --- ##### `ANY`^Required ```typescript public readonly ANY: string; ``` - *Type:* string --- ### CorsOrigins #### Initializers ```typescript import { CorsOrigins } from '@alma-cdk/openapix' new CorsOrigins() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | from | *No description.* | --- ##### `from` ```typescript import { CorsOrigins } from '@alma-cdk/openapix' CorsOrigins.from(scope: Construct, values: ...string[]) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `values`^Required - *Type:* ...string[] --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | ANY | string | *No description.* | --- ##### `ANY`^Required ```typescript public readonly ANY: string; ``` - *Type:* string --- ### HttpIntegration Defines a HTTP(S) integration. #### Initializers ```typescript import { HttpIntegration } from '@alma-cdk/openapix' new HttpIntegration(_: Construct, url: string, props?: HttpIntegrationProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | _ | constructs.Construct | *No description.* | | url | string | *No description.* | | props | HttpIntegrationProps | *No description.* | --- ##### `_`^Required - *Type:* constructs.Construct --- ##### `url`^Required - *Type:* string --- ##### `props`^Optional - *Type:* HttpIntegrationProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### Integration - *Implements:* IBaseIntegration Essentially responsible for converting CDK `IntegrationProps` into API Gateway OpenApi integration extension ()`XAmazonApigatewayIntegration`). Also defines few basic methods (`getIntegration` & `getValidatorId`) used by derivative classes. #### Initializers ```typescript import { Integration } from '@alma-cdk/openapix' new Integration(props: IntegrationProps, config: IntegrationConfig) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | props | aws-cdk-lib.aws_apigateway.IntegrationProps | *No description.* | | config | IntegrationConfig | *No description.* | --- ##### `props`^Required - *Type:* aws-cdk-lib.aws_apigateway.IntegrationProps --- ##### `config`^Required - *Type:* IntegrationConfig --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### LambdaIntegration Defines an AWS Lambda integration. #### Initializers ```typescript import { LambdaIntegration } from '@alma-cdk/openapix' new LambdaIntegration(scope: Construct, fn: IFunction, props?: LambdaIntegrationOptions) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | fn | aws-cdk-lib.aws_lambda.IFunction | *No description.* | | props | LambdaIntegrationOptions | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `fn`^Required - *Type:* aws-cdk-lib.aws_lambda.IFunction --- ##### `props`^Optional - *Type:* LambdaIntegrationOptions --- #### Methods | **Name** | **Description** | | --- | --- | | grantFunctionInvoke | Allow Lambda invoke action to be performed by given identity. | --- ##### `grantFunctionInvoke` ```typescript public grantFunctionInvoke(scope: Construct, executeApiArn: string): void ``` Allow Lambda invoke action to be performed by given identity. ###### `scope`^Required - *Type:* constructs.Construct --- ###### `executeApiArn`^Required - *Type:* string --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | | fn | aws-cdk-lib.aws_lambda.IFunction | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ##### `fn`^Required ```typescript public readonly fn: IFunction; ``` - *Type:* aws-cdk-lib.aws_lambda.IFunction --- ### MockIntegration Defines Mock integration. #### Initializers ```typescript import { MockIntegration } from '@alma-cdk/openapix' new MockIntegration(props?: MockIntegrationProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | props | MockIntegrationProps | *No description.* | --- ##### `props`^Optional - *Type:* MockIntegrationProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### Schema Represents an OpenApi v3 Schema which can be deserialized from YAML-file, modified and then serialized back to YAML. #### Initializers ```typescript import { Schema } from '@alma-cdk/openapix' new Schema(props: SchemaProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | props | SchemaProps | *No description.* | --- ##### `props`^Required - *Type:* SchemaProps --- #### Methods | **Name** | **Description** | | --- | --- | | get | Get a value from given object path. | | has | Check if definition has a value in given object path. | | inject | Inject multiple values to given paths. | | reject | Reject – i.e. remove values – from given object paths. | | rejectDeep | Reject deep within object – i.e. remove all nested object paths. | | set | Set a value to given object path. | | toAsset | Return the OpenApi v3 document as an S3 Asset. | | toDocument | Return the actual OpenApi v3 document. | | toJson | Serialize to JSON string. | | toYaml | Serialize to YAML string. | --- ##### `get` ```typescript public get(path: string): any ``` Get a value from given object path. ###### `path`^Required - *Type:* string --- ##### `has` ```typescript public has(path: string): boolean ``` Check if definition has a value in given object path. ###### `path`^Required - *Type:* string --- ##### `inject` ```typescript public inject(records?: {[ key: string ]: any}): void ``` Inject multiple values to given paths. ###### `records`^Optional - *Type:* {[ key: string ]: any} --- ##### `reject` ```typescript public reject(paths?: string[]): void ``` Reject – i.e. remove values – from given object paths. ###### `paths`^Optional - *Type:* string[] --- ##### `rejectDeep` ```typescript public rejectDeep(paths?: string[]): void ``` Reject deep within object – i.e. remove all nested object paths. ###### `paths`^Optional - *Type:* string[] --- ##### `set` ```typescript public set(path: string, value: any): void ``` Set a value to given object path. ###### `path`^Required - *Type:* string --- ###### `value`^Required - *Type:* any --- ##### `toAsset` ```typescript public toAsset(scope: Construct, id: string): Asset ``` Return the OpenApi v3 document as an S3 Asset. ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### `toDocument` ```typescript public toDocument(): IDocument ``` Return the actual OpenApi v3 document. ##### `toJson` ```typescript public toJson(): string ``` Serialize to JSON string. ##### `toYaml` ```typescript public toYaml(): string ``` Serialize to YAML string. #### Static Functions | **Name** | **Description** | | --- | --- | | fromAsset | Parse OpenApi v3 schema by loading a YAML file from given path. | | fromInline | Parse OpenApi v3 schema from inline YAML content. | --- ##### `fromAsset` ```typescript import { Schema } from '@alma-cdk/openapix' Schema.fromAsset(path: string) ``` Parse OpenApi v3 schema by loading a YAML file from given path. ###### `path`^Required - *Type:* string --- ##### `fromInline` ```typescript import { Schema } from '@alma-cdk/openapix' Schema.fromInline(content: string) ``` Parse OpenApi v3 schema from inline YAML content. ###### `content`^Required - *Type:* string --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | openApiSupportedVersions | string | A string representing supported SemVer range. | | openApiVersion | string | OpenApi version used by schema document. | --- ##### `openApiSupportedVersions`^Required ```typescript public readonly openApiSupportedVersions: string; ``` - *Type:* string A string representing supported SemVer range. > [https://github.com/npm/node-semver](https://github.com/npm/node-semver) --- ##### `openApiVersion`^Required ```typescript public readonly openApiVersion: string; ``` - *Type:* string OpenApi version used by schema document. --- *Example* ```typescript '3.0.3' ``` ## Protocols ### IBaseIntegration - *Implemented By:* AwsIntegration, CorsIntegration, HttpIntegration, Integration, LambdaIntegration, MockIntegration, IBaseIntegration Interface implemented by all integrations. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | InternalIntegrationType | Identifier to enable internal type checks. | | xAmazonApigatewayIntegration | XAmazonApigatewayIntegration | *No description.* | | validator | string | *No description.* | --- ##### `type`^Required ```typescript public readonly type: InternalIntegrationType; ``` - *Type:* InternalIntegrationType Identifier to enable internal type checks. --- ##### `xAmazonApigatewayIntegration`^Required ```typescript public readonly xAmazonApigatewayIntegration: XAmazonApigatewayIntegration; ``` - *Type:* XAmazonApigatewayIntegration --- ##### `validator`^Optional ```typescript public readonly validator: string; ``` - *Type:* string --- ### ICallbackObject - *Extends:* IExtensible - *Implemented By:* ICallbackObject A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. ### IComponentsObject - *Extends:* IExtensible - *Implemented By:* IComponentsObject Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | callbacks | {[ key: string ]: IReferenceObject \| ICallbackObject} | An object to hold reusable Callback Objects. | | examples | {[ key: string ]: IReferenceObject \| IExampleObject} | An object to hold reusable Example Objects. | | headers | {[ key: string ]: IReferenceObject \| IHeaderObject} | An object to hold reusable Header Objects. | | links | {[ key: string ]: IReferenceObject \| ILinkObject} | An object to hold reusable Link Objects. | | parameters | {[ key: string ]: IReferenceObject \| IParameterObject} | An object to hold reusable Parameter Objects. | | requestBodies | {[ key: string ]: IReferenceObject \| IRequestBodyObject} | An object to hold reusable Request Body Objects. | | responses | {[ key: string ]: IReferenceObject \| IResponseObject} | An object to hold reusable Response Objects. | | schemas | {[ key: string ]: IReferenceObject \| ISchemaObject} | An object to hold reusable Schema Objects. | | securitySchemes | {[ key: string ]: IReferenceObject \| ISecuritySchemeObject} | An object to hold reusable Security Scheme Objects. | --- ##### `callbacks`^Optional ```typescript public readonly callbacks: {[ key: string ]: IReferenceObject | ICallbackObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ICallbackObject} An object to hold reusable Callback Objects. --- ##### `examples`^Optional ```typescript public readonly examples: {[ key: string ]: IReferenceObject | IExampleObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IExampleObject} An object to hold reusable Example Objects. --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: IReferenceObject | IHeaderObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IHeaderObject} An object to hold reusable Header Objects. --- ##### `links`^Optional ```typescript public readonly links: {[ key: string ]: IReferenceObject | ILinkObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ILinkObject} An object to hold reusable Link Objects. --- ##### `parameters`^Optional ```typescript public readonly parameters: {[ key: string ]: IReferenceObject | IParameterObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IParameterObject} An object to hold reusable Parameter Objects. --- ##### `requestBodies`^Optional ```typescript public readonly requestBodies: {[ key: string ]: IReferenceObject | IRequestBodyObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IRequestBodyObject} An object to hold reusable Request Body Objects. --- ##### `responses`^Optional ```typescript public readonly responses: {[ key: string ]: IReferenceObject | IResponseObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IResponseObject} An object to hold reusable Response Objects. --- ##### `schemas`^Optional ```typescript public readonly schemas: {[ key: string ]: IReferenceObject | ISchemaObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ISchemaObject} An object to hold reusable Schema Objects. --- ##### `securitySchemes`^Optional ```typescript public readonly securitySchemes: {[ key: string ]: IReferenceObject | ISecuritySchemeObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ISecuritySchemeObject} An object to hold reusable Security Scheme Objects. --- ### IContactObject - *Extends:* IExtensible - *Implemented By:* IContactObject The contact information for the exposed API. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | email | string | The email address of the contact person/organization. | | name | string | The identifying name of the contact person/organization. | | url | string | The URL pointing to the contact information. | --- ##### `email`^Optional ```typescript public readonly email: string; ``` - *Type:* string The email address of the contact person/organization. MUST be in the format of an email address. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string The identifying name of the contact person/organization. --- ##### `url`^Optional ```typescript public readonly url: string; ``` - *Type:* string The URL pointing to the contact information. MUST be in the format of a URL. --- ### IDiscriminatorObject - *Extends:* IExtensible - *Implemented By:* IDiscriminatorObject When request bodies or response payloads may be one of a number of different schemas, a discriminator object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, inline schemas will not be considered. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | propertyName | string | The name of the property in the payload that will hold the discriminator value. | | mapping | {[ key: string ]: string} | An object to hold mappings between payload values and schema names or references. | --- ##### `propertyName`^Required ```typescript public readonly propertyName: string; ``` - *Type:* string The name of the property in the payload that will hold the discriminator value. --- ##### `mapping`^Optional ```typescript public readonly mapping: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} An object to hold mappings between payload values and schema names or references. --- ### IDocument - *Extends:* IExtensible - *Implemented By:* IDocument Describes a mutable OpenApi v3 Document. Essentially the same as `SchemaProps` but without `readonly` definitions. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | info | IInfoObject | Provides metadata about the API. | | openapi | string | This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. | | paths | IPathsObject | The available paths and operations for the API. | | components | IComponentsObject | An element to hold various schemas for the specification. | | externalDocs | IExternalDocumentationObject | Additional external documentation. | | security | ISecurityRequirementObject[] | A declaration of which security mechanisms can be used across the API. | | servers | IServerObject[] | An array of Server Objects, which provide connectivity information to a target server. | | tags | ITagObject[] | A list of tags used by the specification with additional metadata. | --- ##### `info`^Required ```typescript public readonly info: IInfoObject; ``` - *Type:* IInfoObject Provides metadata about the API. The metadata MAY be used by tooling as required. --- *Example* ```typescript { title: "FancyPants API", version: "1.23.105", } ``` ##### `openapi`^Required ```typescript public readonly openapi: string; ``` - *Type:* string This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string. --- *Example* ```typescript '3.0.0' ``` ##### `paths`^Required ```typescript public readonly paths: IPathsObject; ``` - *Type:* IPathsObject The available paths and operations for the API. --- ##### `components`^Optional ```typescript public readonly components: IComponentsObject; ``` - *Type:* IComponentsObject An element to hold various schemas for the specification. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: IExternalDocumentationObject; ``` - *Type:* IExternalDocumentationObject Additional external documentation. --- ##### `security`^Optional ```typescript public readonly security: ISecurityRequirementObject[]; ``` - *Type:* ISecurityRequirementObject[] A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array. --- ##### `servers`^Optional ```typescript public readonly servers: IServerObject[]; ``` - *Type:* IServerObject[] An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /. --- ##### `tags`^Optional ```typescript public readonly tags: ITagObject[]; ``` - *Type:* ITagObject[] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. --- ### IEncodingObject - *Extends:* IExtensible - *Implemented By:* IEncodingObject A single encoding definition applied to a single schema property. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowReserved | boolean | Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. | | contentType | string | The Content-Type for encoding a specific property. | | explode | boolean | When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. | | headers | {[ key: string ]: IReferenceObject \| IHeaderObject} | A map allowing additional information to be provided as headers, for example Content-Disposition. | | style | string | Describes how a specific property value will be serialized depending on its type. | --- ##### `allowReserved`^Optional ```typescript public readonly allowReserved: boolean; ``` - *Type:* boolean Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ##### `contentType`^Optional ```typescript public readonly contentType: string; ``` - *Type:* string The Content-Type for encoding a specific property. Default value depends on the property type: for string with format being binary – application/octet-stream; for other primitive types – text/plain; for object - application/json; for array – the default is defined based on the inner type. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types. --- ##### `explode`^Optional ```typescript public readonly explode: boolean; ``` - *Type:* boolean When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When style is form, the default value is true. For all other styles, the default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: IReferenceObject | IHeaderObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IHeaderObject} A map allowing additional information to be provided as headers, for example Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a multipart. --- ##### `style`^Optional ```typescript public readonly style: string; ``` - *Type:* string Describes how a specific property value will be serialized depending on its type. See Parameter Object for details on the style property. The behavior follows the same values as query parameters, including default values. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. --- ### IExampleObject - *Extends:* IExtensible - *Implemented By:* IExampleObject Example Object. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | Long description for the example. | | externalValue | string | A URL that points to the literal example. | | summary | string | Short description for the example. | | value | any | Embedded literal example. | --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string Long description for the example. CommonMark syntax MAY be used for rich text representation. --- ##### `externalValue`^Optional ```typescript public readonly externalValue: string; ``` - *Type:* string A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The value field and externalValue field are mutually exclusive. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string Short description for the example. --- ##### `value`^Optional ```typescript public readonly value: any; ``` - *Type:* any Embedded literal example. The value field and externalValue field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. --- ### IExtensible - *Implemented By:* ICallbackObject, IComponentsObject, IContactObject, IDiscriminatorObject, IDocument, IEncodingObject, IExampleObject, IExtensible, IExternalDocumentationObject, IHeaderObject, IInfoObject, ILicenseObject, ILinkObject, IMediaTypeObject, IOAuthFlowObject, IOAuthFlowsObject, IOperationObject, IParameterObject, IPathItemObject, IPathsObject, IReferenceObject, IRequestBodyObject, IResponseObject, IResponsesObject, ISchemaObject, ISecurityRequirementObject, ISecuritySchemeObject, IServerObject, IServerVariableObject, ITagObject, IXmlObject Allow Open Api Extensions via `x-` prefixed values. ### IExternalDocumentationObject - *Extends:* IExtensible - *Implemented By:* IExternalDocumentationObject Allows referencing an external resource for extended documentation. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | url | string | The URL for the target documentation. | | description | string | A short description of the target documentation. | --- ##### `url`^Required ```typescript public readonly url: string; ``` - *Type:* string The URL for the target documentation. Value MUST be in the format of a URL. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description of the target documentation. CommonMark syntax MAY be used for rich text representation. --- ### IHeaderObject - *Extends:* IExtensible - *Implemented By:* IHeaderObject The Header Object follows the structure of the Parameter Object with the following changes:. 1. name MUST NOT be specified, it is given in the corresponding headers map. 2. in MUST NOT be specified, it is implicitly in header. 3. All traits that are affected by the location MUST be applicable to a location of header (for example, style). #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowEmptyValue | boolean | Sets the ability to pass empty-valued parameters. | | deprecated | boolean | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. | | description | string | A brief description of the parameter. | | required | boolean | Determines whether this parameter is mandatory. | --- ##### `allowEmptyValue`^Optional ```typescript public readonly allowEmptyValue: boolean; ``` - *Type:* boolean Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. --- ### IInfoObject - *Extends:* IExtensible - *Implemented By:* IInfoObject The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | title | string | The title of the API. | | version | string | The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). | | contact | IContactObject | The contact information for the exposed API. | | description | string | A short description of the API. | | license | ILicenseObject | The license information for the exposed API. | | termsOfService | string | A URL to the Terms of Service for the API. | --- ##### `title`^Required ```typescript public readonly title: string; ``` - *Type:* string The title of the API. --- ##### `version`^Required ```typescript public readonly version: string; ``` - *Type:* string The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). --- ##### `contact`^Optional ```typescript public readonly contact: IContactObject; ``` - *Type:* IContactObject The contact information for the exposed API. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description of the API. CommonMark syntax MAY be used for rich text representation. --- ##### `license`^Optional ```typescript public readonly license: ILicenseObject; ``` - *Type:* ILicenseObject The license information for the exposed API. --- ##### `termsOfService`^Optional ```typescript public readonly termsOfService: string; ``` - *Type:* string A URL to the Terms of Service for the API. MUST be in the format of a URL. --- ### ILicenseObject - *Extends:* IExtensible - *Implemented By:* ILicenseObject The license information for the exposed API. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | The license name used for the API. | | url | string | A URL to the license used for the API. | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The license name used for the API. --- ##### `url`^Optional ```typescript public readonly url: string; ``` - *Type:* string A URL to the license used for the API. MUST be in the format of a URL. --- ### ILinkObject - *Extends:* IExtensible - *Implemented By:* ILinkObject The Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | A description of the link. | | operationId | string | The name of an existing, resolvable OAS operation, as defined with a unique operationId. | | operationRef | string | A relative or absolute URI reference to an OAS operation. | | parameters | {[ key: string ]: any} | A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. | | requestBody | any | A literal value or {expression} to use as a request body when calling the target operation. | | server | IServerObject | A server object to be used by the target operation. | --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A description of the link. CommonMark syntax MAY be used for rich text representation. --- ##### `operationId`^Optional ```typescript public readonly operationId: string; ``` - *Type:* string The name of an existing, resolvable OAS operation, as defined with a unique operationId. This field is mutually exclusive of the operationRef field. --- ##### `operationRef`^Optional ```typescript public readonly operationRef: string; ``` - *Type:* string A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the operationId field, and MUST point to an Operation Object. Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition. --- ##### `parameters`^Optional ```typescript public readonly parameters: {[ key: string ]: any}; ``` - *Type:* {[ key: string ]: any} A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id). --- ##### `requestBody`^Optional ```typescript public readonly requestBody: any; ``` - *Type:* any A literal value or {expression} to use as a request body when calling the target operation. --- ##### `server`^Optional ```typescript public readonly server: IServerObject; ``` - *Type:* IServerObject A server object to be used by the target operation. --- ### IMediaTypeObject - *Extends:* IExtensible - *Implemented By:* IMediaTypeObject Each Media Type Object provides schema and examples for the media type identified by its key. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | encoding | {[ key: string ]: IEncodingObject} | A map between a property name and its encoding information. | | example | any | Example of the media type. | | examples | {[ key: string ]: IReferenceObject \| IExampleObject} | Examples of the media type. | | schema | IReferenceObject \| ISchemaObject | The schema defining the content of the request, response, or parameter. | --- ##### `encoding`^Optional ```typescript public readonly encoding: {[ key: string ]: IEncodingObject}; ``` - *Type:* {[ key: string ]: IEncodingObject} A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded. --- ##### `example`^Optional ```typescript public readonly example: any; ``` - *Type:* any Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The example field is mutually exclusive of the examples field. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. --- ##### `examples`^Optional ```typescript public readonly examples: {[ key: string ]: IReferenceObject | IExampleObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IExampleObject} Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema. --- ##### `schema`^Optional ```typescript public readonly schema: IReferenceObject | ISchemaObject; ``` - *Type:* IReferenceObject | ISchemaObject The schema defining the content of the request, response, or parameter. --- ### IOAuthFlowObject - *Extends:* IExtensible - *Implemented By:* IOAuthFlowObject Configuration details for a supported OAuth Flow. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | scopes | {[ key: string ]: string} | The available scopes for the OAuth2 security scheme. | | authorizationUrl | string | The authorization URL to be used for this flow. | | refreshUrl | string | The URL to be used for obtaining refresh tokens. | | tokenUrl | string | The token URL to be used for this flow. | --- ##### `scopes`^Required ```typescript public readonly scopes: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. --- ##### `authorizationUrl`^Optional ```typescript public readonly authorizationUrl: string; ``` - *Type:* string The authorization URL to be used for this flow. This MUST be in the form of a URL. REQUIRED for oauth2 ("implicit", "authorizationCode"). --- ##### `refreshUrl`^Optional ```typescript public readonly refreshUrl: string; ``` - *Type:* string The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. --- ##### `tokenUrl`^Optional ```typescript public readonly tokenUrl: string; ``` - *Type:* string The token URL to be used for this flow. This MUST be in the form of a URL. REQUIRED for oauth2 ("password", "clientCredentials", "authorizationCode"). --- ### IOAuthFlowsObject - *Extends:* IExtensible - *Implemented By:* IOAuthFlowsObject Allows configuration of the supported OAuth Flows. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | authorizationCode | IOAuthFlowObject | Configuration for the OAuth Authorization Code flow. | | clientCredentials | IOAuthFlowObject | Configuration for the OAuth Client Credentials flow. | | implicit | IOAuthFlowObject | Configuration for the OAuth Implicit flow. | | password | IOAuthFlowObject | Configuration for the OAuth Resource Owner Password flow. | --- ##### `authorizationCode`^Optional ```typescript public readonly authorizationCode: IOAuthFlowObject; ``` - *Type:* IOAuthFlowObject Configuration for the OAuth Authorization Code flow. Previously called accessCode in OpenAPI 2.0. --- ##### `clientCredentials`^Optional ```typescript public readonly clientCredentials: IOAuthFlowObject; ``` - *Type:* IOAuthFlowObject Configuration for the OAuth Client Credentials flow. Previously called application in OpenAPI 2.0. --- ##### `implicit`^Optional ```typescript public readonly implicit: IOAuthFlowObject; ``` - *Type:* IOAuthFlowObject Configuration for the OAuth Implicit flow. --- ##### `password`^Optional ```typescript public readonly password: IOAuthFlowObject; ``` - *Type:* IOAuthFlowObject Configuration for the OAuth Resource Owner Password flow. --- ### IOperationObject - *Extends:* IExtensible - *Implemented By:* IOperationObject Describes a single API operation on a path. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | responses | IResponsesObject | The list of possible responses as they are returned from executing this operation. | | callbacks | {[ key: string ]: IReferenceObject \| ICallbackObject} | A map of possible out-of band callbacks related to the parent operation. | | deprecated | boolean | Declares this operation to be deprecated. | | description | string | A verbose explanation of the operation behavior. | | externalDocs | IExternalDocumentationObject | Additional external documentation for this operation. | | operationId | string | Unique string used to identify the operation. | | parameters | IReferenceObject \| IParameterObject[] | A list of parameters that are applicable for this operation. | | requestBody | IReferenceObject \| IRequestBodyObject | The request body applicable for this operation. | | security | ISecurityRequirementObject[] | A declaration of which security mechanisms can be used for this operation. | | summary | string | A short summary of what the operation does. | | tags | string[] | A list of tags for API documentation control. | --- ##### `responses`^Required ```typescript public readonly responses: IResponsesObject; ``` - *Type:* IResponsesObject The list of possible responses as they are returned from executing this operation. --- ##### `callbacks`^Optional ```typescript public readonly callbacks: {[ key: string ]: IReferenceObject | ICallbackObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ICallbackObject} A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: IExternalDocumentationObject; ``` - *Type:* IExternalDocumentationObject Additional external documentation for this operation. --- ##### `operationId`^Optional ```typescript public readonly operationId: string; ``` - *Type:* string Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. --- ##### `parameters`^Optional ```typescript public readonly parameters: (IReferenceObject | IParameterObject)[]; ``` - *Type:* IReferenceObject | IParameterObject[] A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters. --- ##### `requestBody`^Optional ```typescript public readonly requestBody: IReferenceObject | IRequestBodyObject; ``` - *Type:* IReferenceObject | IRequestBodyObject The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers. --- ##### `security`^Optional ```typescript public readonly security: ISecurityRequirementObject[]; ``` - *Type:* ISecurityRequirementObject[] A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement ({}) can be included in the array. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string A short summary of what the operation does. --- ##### `tags`^Optional ```typescript public readonly tags: string[]; ``` - *Type:* string[] A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. --- ### IParameterObject - *Extends:* IExtensible - *Implemented By:* IParameterObject Describes a single operation parameter. A unique parameter is defined by a combination of a name and location. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | in | string | The location of the parameter. | | name | string | The name of the parameter. Parameter names are case sensitive. | | allowEmptyValue | boolean | Sets the ability to pass empty-valued parameters. | | deprecated | boolean | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. | | description | string | A brief description of the parameter. | | required | boolean | Determines whether this parameter is mandatory. | --- ##### `in`^Required ```typescript public readonly in: string; ``` - *Type:* string The location of the parameter. Possible values are "query", "header", "path" or "cookie". --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The name of the parameter. Parameter names are case sensitive. If in is "path", the name field MUST correspond to a template expression occurring within the path field in the Paths Object. See Path Templating for further information. If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored. For all other cases, the name corresponds to the parameter name used by the in property. --- ##### `allowEmptyValue`^Optional ```typescript public readonly allowEmptyValue: boolean; ``` - *Type:* boolean Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. --- ### IPathItemObject - *Extends:* IExtensible - *Implemented By:* IPathItemObject Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | delete | IOperationObject | A definition of a DELETE operation on this path. | | description | string | An optional, string description, intended to apply to all operations in this path. | | get | IOperationObject | A definition of a GET operation on this path. | | head | IOperationObject | A definition of a HEAD operation on this path. | | options | IOperationObject | A definition of a OPTIONS operation on this path. | | parameters | IReferenceObject \| IParameterObject[] | A list of parameters that are applicable for all the operations described under this path. | | patch | IOperationObject | A definition of a PATCH operation on this path. | | post | IOperationObject | A definition of a POST operation on this path. | | put | IOperationObject | A definition of a PUT operation on this path. | | summary | string | An optional, string summary, intended to apply to all operations in this path. | | trace | IOperationObject | A definition of a TRACE operation on this path. | --- ##### `delete`^Optional ```typescript public readonly delete: IOperationObject; ``` - *Type:* IOperationObject A definition of a DELETE operation on this path. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation. --- ##### `get`^Optional ```typescript public readonly get: IOperationObject; ``` - *Type:* IOperationObject A definition of a GET operation on this path. --- ##### `head`^Optional ```typescript public readonly head: IOperationObject; ``` - *Type:* IOperationObject A definition of a HEAD operation on this path. --- ##### `options`^Optional ```typescript public readonly options: IOperationObject; ``` - *Type:* IOperationObject A definition of a OPTIONS operation on this path. --- ##### `parameters`^Optional ```typescript public readonly parameters: (IReferenceObject | IParameterObject)[]; ``` - *Type:* IReferenceObject | IParameterObject[] A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters. --- ##### `patch`^Optional ```typescript public readonly patch: IOperationObject; ``` - *Type:* IOperationObject A definition of a PATCH operation on this path. --- ##### `post`^Optional ```typescript public readonly post: IOperationObject; ``` - *Type:* IOperationObject A definition of a POST operation on this path. --- ##### `put`^Optional ```typescript public readonly put: IOperationObject; ``` - *Type:* IOperationObject A definition of a PUT operation on this path. --- ##### `summary`^Optional ```typescript public readonly summary: string; ``` - *Type:* string An optional, string summary, intended to apply to all operations in this path. --- ##### `trace`^Optional ```typescript public readonly trace: IOperationObject; ``` - *Type:* IOperationObject A definition of a TRACE operation on this path. --- ### IPathsObject - *Extends:* IExtensible - *Implemented By:* IPathsObject Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to ACL constraints. ### IReferenceObject - *Extends:* IExtensible - *Implemented By:* IReferenceObject A simple object to allow referencing other components in the specification, internally and externally. ### IRequestBodyObject - *Extends:* IExtensible - *Implemented By:* IRequestBodyObject Describes a single request body. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | content | {[ key: string ]: IMediaTypeObject} | The content of the request body. | | description | string | A brief description of the request body. | | required | boolean | Determines if the request body is required in the request. | --- ##### `content`^Required ```typescript public readonly content: {[ key: string ]: IMediaTypeObject}; ``` - *Type:* {[ key: string ]: IMediaTypeObject} The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation. --- ##### `required`^Optional ```typescript public readonly required: boolean; ``` - *Type:* boolean Determines if the request body is required in the request. Defaults to false. --- ### IResponseObject - *Extends:* IExtensible - *Implemented By:* IResponseObject Describes a single response from an API Operation, including design-time, static links to operations based on the response. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | description | string | A short description of the response. | | content | {[ key: string ]: IReferenceObject \| IMediaTypeObject} | A map containing descriptions of potential response payloads. | | headers | {[ key: string ]: IReferenceObject \| IHeaderObject} | Maps a header name to its definition. | | links | {[ key: string ]: IReferenceObject \| ILinkObject} | A map of operations links that can be followed from the response. | --- ##### `description`^Required ```typescript public readonly description: string; ``` - *Type:* string A short description of the response. CommonMark syntax MAY be used for rich text representation. --- ##### `content`^Optional ```typescript public readonly content: {[ key: string ]: IReferenceObject | IMediaTypeObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IMediaTypeObject} A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* --- ##### `headers`^Optional ```typescript public readonly headers: {[ key: string ]: IReferenceObject | IHeaderObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | IHeaderObject} Maps a header name to its definition. RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored. --- ##### `links`^Optional ```typescript public readonly links: {[ key: string ]: IReferenceObject | ILinkObject}; ``` - *Type:* {[ key: string ]: IReferenceObject | ILinkObject} A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects. --- ### IResponsesObject - *Extends:* IExtensible - *Implemented By:* IResponsesObject A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The default MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ### ISchemaObject - *Extends:* IExtensible - *Implemented By:* ISchemaObject The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00. For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | deprecated | boolean | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. | | discriminator | IDiscriminatorObject | Adds support for polymorphism. | | example | any | A free-form property to include an example of an instance for this schema. | | externalDocs | IExternalDocumentationObject | Additional external documentation for this schema. | | nullable | boolean | A true value adds "null" to the allowed type specified by the type keyword, only if type is explicitly defined within the same Schema Object. | | readOnly | boolean | Relevant only for Schema "properties" definitions. | | writeOnly | boolean | Relevant only for Schema "properties" definitions. | | xml | IXmlObject | This MAY be used only on properties schemas. | --- ##### `deprecated`^Optional ```typescript public readonly deprecated: boolean; ``` - *Type:* boolean Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false. --- ##### `discriminator`^Optional ```typescript public readonly discriminator: IDiscriminatorObject; ``` - *Type:* IDiscriminatorObject Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details. --- ##### `example`^Optional ```typescript public readonly example: any; ``` - *Type:* any A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: IExternalDocumentationObject; ``` - *Type:* IExternalDocumentationObject Additional external documentation for this schema. --- ##### `nullable`^Optional ```typescript public readonly nullable: boolean; ``` - *Type:* boolean A true value adds "null" to the allowed type specified by the type keyword, only if type is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of null as a value. A false value leaves the specified or default type unmodified. The default value is false. --- ##### `readOnly`^Optional ```typescript public readonly readOnly: boolean; ``` - *Type:* boolean Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both and writeOnly being true. Default value is false. --- ##### `writeOnly`^Optional ```typescript public readonly writeOnly: boolean; ``` - *Type:* boolean Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both and writeOnly being true. Default value is false. --- ##### `xml`^Optional ```typescript public readonly xml: IXmlObject; ``` - *Type:* IXmlObject This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. --- ### ISecurityRequirementObject - *Extends:* IExtensible - *Implemented By:* ISecurityRequirementObject Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object, only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request. ### ISecuritySchemeObject - *Extends:* IExtensible - *Implemented By:* ISecuritySchemeObject Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | type | string | The type of the security scheme. | | bearerFormat | string | A hint to the client to identify how the bearer token is formatted. | | description | string | A short description for security scheme. | | flow | IOAuthFlowsObject | An object containing configuration information for the flow types supported. | | in | string | The location of the API key. | | name | string | The name of the header, query or cookie parameter to be used. | | openIdConnectUrl | string | OpenId Connect URL to discover OAuth2 configuration values. | | scheme | string | The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. | --- ##### `type`^Required ```typescript public readonly type: string; ``` - *Type:* string The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect". --- ##### `bearerFormat`^Optional ```typescript public readonly bearerFormat: string; ``` - *Type:* string A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description for security scheme. CommonMark syntax MAY be used for rich text representation. --- ##### `flow`^Optional ```typescript public readonly flow: IOAuthFlowsObject; ``` - *Type:* IOAuthFlowsObject An object containing configuration information for the flow types supported. REQUIRED for oauth2. --- ##### `in`^Optional ```typescript public readonly in: string; ``` - *Type:* string The location of the API key. Valid values are "query", "header" or "cookie". REQUIRED for apiKey. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string The name of the header, query or cookie parameter to be used. REQUIRED for apiKey. --- ##### `openIdConnectUrl`^Optional ```typescript public readonly openIdConnectUrl: string; ``` - *Type:* string OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. REQUIRED for openIdConnect. --- ##### `scheme`^Optional ```typescript public readonly scheme: string; ``` - *Type:* string The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry. REQUIRED for http. --- ### IServerObject - *Extends:* IExtensible - *Implemented By:* IServerObject An object representing a Server. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | url | string | REQUIRED. | | description | string | An optional string describing the host designated by the URL. | | variables | {[ key: string ]: IServerVariableObject} | A map between a variable name and its value. | --- ##### `url`^Required ```typescript public readonly url: string; ``` - *Type:* string REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation. --- ##### `variables`^Optional ```typescript public readonly variables: {[ key: string ]: IServerVariableObject}; ``` - *Type:* {[ key: string ]: IServerVariableObject} A map between a variable name and its value. The value is used for substitution in the server's URL template. --- ### IServerVariableObject - *Extends:* IExtensible - *Implemented By:* IServerVariableObject An object representing a Server Variable for server URL template substitution. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | default | string | The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. | | description | string | An optional description for the server variable. | | enum | string[] | An enumeration of string values to be used if the substitution options are from a limited set. | --- ##### `default`^Required ```typescript public readonly default: string; ``` - *Type:* string The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object's treatment of default values, because in those cases parameter values are optional. If the enum is defined, the value SHOULD exist in the enum's values. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string An optional description for the server variable. CommonMark syntax MAY be used for rich text representation. --- ##### `enum`^Optional ```typescript public readonly enum: string[]; ``` - *Type:* string[] An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. --- ### ITagObject - *Extends:* IExtensible - *Implemented By:* ITagObject Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | The name of the tag. | | description | string | A short description for the tag. | | externalDocs | IExternalDocumentationObject | Additional external documentation for this tag. | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string The name of the tag. --- ##### `description`^Optional ```typescript public readonly description: string; ``` - *Type:* string A short description for the tag. CommonMark syntax MAY be used for rich text representation. --- ##### `externalDocs`^Optional ```typescript public readonly externalDocs: IExternalDocumentationObject; ``` - *Type:* IExternalDocumentationObject Additional external documentation for this tag. --- ### IXmlObject - *Extends:* IExtensible - *Implemented By:* IXmlObject A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are not inferred (for singular/plural forms) and the name property SHOULD be used to add that information. See examples for expected behavior. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | attribute | boolean | Declares whether the property definition translates to an attribute instead of an element. | | name | string | Replaces the name of the element/attribute used for the described schema property. | | namespace | string | The URI of the namespace definition. | | prefix | string | The prefix to be used for the name. | | wrapped | boolean | MAY be used only for an array definition. | --- ##### `attribute`^Optional ```typescript public readonly attribute: boolean; ``` - *Type:* boolean Declares whether the property definition translates to an attribute instead of an element. Default value is false. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string Replaces the name of the element/attribute used for the described schema property. When defined within items, it will affect the name of the individual XML elements within the list. When defined alongside type being array (outside the items), it will affect the wrapping element and only if wrapped is true. If wrapped is false, it will be ignored. --- ##### `namespace`^Optional ```typescript public readonly namespace: string; ``` - *Type:* string The URI of the namespace definition. Value MUST be in the form of an absolute URI. --- ##### `prefix`^Optional ```typescript public readonly prefix: string; ``` - *Type:* string The prefix to be used for the name. --- ##### `wrapped`^Optional ```typescript public readonly wrapped: boolean; ``` - *Type:* boolean MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ) or unwrapped (). Default value is false. The definition takes effect only when defined alongside type being array (outside the items). --- ## Enums ### InternalIntegrationType #### Members | **Name** | **Description** | | --- | --- | | AWS | *No description.* | | CORS | *No description.* | | HTTP | *No description.* | | LAMBDA | *No description.* | | MOCK | *No description.* | --- ##### `AWS` --- ##### `CORS` --- ##### `HTTP` --- ##### `LAMBDA` --- ##### `MOCK` ---