Skip to content

docs: change references to Swagger to OpenAPI #1199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 18, 2019
Merged

docs: change references to Swagger to OpenAPI #1199

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions versions/2016-10-31.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,16 +212,16 @@ Layers:

Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.

An `AWS::Serverless::Api` resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of [Api](#api) events defined on `AWS::Serverless::Function` resources defined in the template that do not refer to an `AWS::Serverless::Api` resource. An `AWS::Serverless::Api` resource should be used to define and document the API using Swagger, which provides more ability to configure the underlying Amazon API Gateway resources.
An `AWS::Serverless::Api` resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of [Api](#api) events defined on `AWS::Serverless::Function` resources defined in the template that do not refer to an `AWS::Serverless::Api` resource. An `AWS::Serverless::Api` resource should be used to define and document the API using [OpenAPI](https://github.com/OAI/OpenAPI-Specification), which provides more ability to configure the underlying Amazon API Gateway resources.

##### Properties

Property Name | Type | Description
---|:---:|---
Name | `string` | A name for the API Gateway RestApi resource.
StageName | `string` | **Required** The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI).
DefinitionUri | `string` <span>&#124;</span> [S3 Location Object](#s3-location-object) | S3 URI or location to the Swagger document describing the API. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration. **Note** Intrinsic functions are not supported in external Swagger files, instead use DefinitionBody to define Swagger definition.
DefinitionBody | `JSON or YAML Object` | Swagger specification that describes your API. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration.
DefinitionUri | `string` <span>&#124;</span> [S3 Location Object](#s3-location-object) | S3 URI or location to the OpenAPI document describing the API. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration. **Note** Intrinsic functions are not supported in external OpenAPI files, instead use DefinitionBody to define OpenAPI definition.
DefinitionBody | `JSON or YAML Object` | OpenAPI specification that describes your API. If neither `DefinitionUri` nor `DefinitionBody` are specified, SAM will generate a `DefinitionBody` for you based on your template configuration.
CacheClusterEnabled | `boolean` | Indicates whether cache clustering is enabled for the stage.
CacheClusterSize | `string` | The stage's cache cluster size.
Variables | Map of `string` to `string` | A map (string to string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: `[A-Za-z0-9._~:/?#&amp;=,-]+`.
Expand All @@ -230,7 +230,7 @@ Tags | Map of `string` to `string` | A map (string to string) that specifies the
EndpointConfiguration | `string` | Specify the type of endpoint for API endpoint. Value is either `REGIONAL`, `EDGE`, or `PRIVATE`.
BinaryMediaTypes | List of `string` | List of MIME types that your API could return. Use this to enable binary support for APIs. Use `~1` instead of `/` in the mime types (See examples in [template.yaml](../examples/2016-10-31/implicit_api_settings/template.yaml)).
MinimumCompressionSize | `int` | Allow compression of response bodies based on client's Accept-Encoding header. Compression is triggered when response body size is greater than or equal to your configured threshold. The maximum body size threshold is 10 MB (10,485,760 Bytes). The following compression types are supported: gzip, deflate, and identity.
Cors | `string` or [Cors Configuration](#cors-configuration) | Enable CORS for all your APIs. Specify the domain to allow as a string or specify a dictionary with additional [Cors Configuration](#cors-configuration). NOTE: Cors requires SAM to modify your Swagger definition. Hence it works only inline swagger defined with `DefinitionBody`.
Cors | `string` or [Cors Configuration](#cors-configuration) | Enable CORS for all your APIs. Specify the domain to allow as a string or specify a dictionary with additional [Cors Configuration](#cors-configuration). NOTE: Cors requires SAM to modify your OpenAPI definition. Hence it works only inline OpenAPI defined with `DefinitionBody`.
Auth | [API Auth Object](#api-auth-object) | Auth configuration for this API. Define Lambda and Cognito `Authorizers` and specify a `DefaultAuthorizer` for this API. Can specify default ApiKey restriction using `ApiKeyRequired`. Also define `ResourcePolicy` and specify `CustomStatements` which is a list of policy statements that will be added to the resource policies on the API. To whitelist specific AWS accounts, add `AwsAccountWhitelist: [<list of account ids>]` under ResourcePolicy. Similarly, `AwsAccountBlacklist`, `IpRangeWhitelist`, `IpRangeBlacklist`, `SourceVpcWhitelist`, `SourceVpcBlacklist` are also supported.
GatewayResponses | Map of [Gateway Response Type](https://docs.aws.amazon.com/apigateway/api-reference/resource/gateway-response/) to [Gateway Response Object](#gateway-response-object) | Configures Gateway Reponses for an API. Gateway Responses are responses returned by API Gateway, either directly or through the use of Lambda Authorizers. Keys for this object are passed through to Api Gateway, so any value supported by `GatewayResponse.responseType` is supported here.
AccessLogSetting | [CloudFormation AccessLogSetting property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-accesslogsetting.html) | Configures Access Log Setting for a stage. This value is passed through to CloudFormation, so any value supported by `AccessLogSetting` is supported here.
Expand All @@ -248,7 +248,7 @@ When the logical ID of this resource is provided to the [Ref intrinsic function]

```yaml
StageName: prod
DefinitionUri: swagger.yml
DefinitionUri: openapi.yml
```

###### Referencing generated resources - Stage & Deployment
Expand Down Expand Up @@ -529,15 +529,15 @@ Properties:

The object describing an event source with type `Api`.

If an [AWS::Serverless::Api](#aws-serverless-api) resource is defined, the path and method values MUST correspond to an operation in the Swagger definition of the API. If no [AWS::Serverless::Api](#aws-serverless-api) is defined, the function input and output are a representation of the HTTP request and HTTP response. For example, using the JavaScript API, the status code and body of the response can be controlled by returning an object with the keys `statusCode` and `body`.
If an [AWS::Serverless::Api](#aws-serverless-api) resource is defined, the path and method values MUST correspond to an operation in the OpenAPI definition of the API. If no [AWS::Serverless::Api](#aws-serverless-api) is defined, the function input and output are a representation of the HTTP request and HTTP response. For example, using the JavaScript API, the status code and body of the response can be controlled by returning an object with the keys `statusCode` and `body`.

##### Properties

Property Name | Type | Description
---|:---:|---
Path | `string` | **Required.** Uri path for which this function is invoked. MUST start with `/`.
Method | `string` | **Required.** HTTP method for which this function is invoked.
RestApiId | `string` | Identifier of a RestApi resource which MUST contain an operation with the given path and method. Typically, this is set to [reference](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) an `AWS::Serverless::Api` resource defined in this template. If not defined, a default `AWS::Serverless::Api` resource is created using a generated Swagger document contains a union of all paths and methods defined by `Api` events defined in this template that do not specify a RestApiId.
RestApiId | `string` | Identifier of a RestApi resource which MUST contain an operation with the given path and method. Typically, this is set to [reference](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) an `AWS::Serverless::Api` resource defined in this template. If not defined, a default `AWS::Serverless::Api` resource is created using a generated OpenAPI document contains a union of all paths and methods defined by `Api` events defined in this template that do not specify a RestApiId.
Auth | [Function Auth Object](#function-auth-object) | Auth configuration for this specific Api+Path+Method. Useful for overriding the API's `DefaultAuthorizer` setting auth config on an individual path when no `DefaultAuthorizer` is specified or overriding the default `ApiKeyRequired` setting.
RequestModel | [Function Request Model Object](#function-request-model-object) | Request model configuration for this specific Api+Path+Method.
RequestParameters | List of `string` <span>&#124;</span> List of [Function Request Parameter Object](#function-request-parameter-object) | Request parameters configuration for this specific Api+Path+Method. All parameter names must start with `method.request` and must be limited to `method.request.header`, `method.request.querystring`, or `method.request.path`. If a parameter is a `string` and NOT a [Function Request Parameter Object](#function-request-parameter-object) then `Required` and `Caching` will default to `False`.
Expand Down