API Gateway Property Updates and Improved Validation Coverage

[bmurtagh]

This should close #550 once merged

[bmurtagh]

@markpeek @phobologic i do have a question regarding the validate for the RestApi(AWSObject) in regards to the Name property. See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name

The documentation for Name states, "Required: Conditional. Required if you don't specify a OpenAPI definition."

I assume this OpenAPI definition would be stored in the Body parameter, but the Body property's documentation states, "An OpenAPI specification that defines a set of RESTful APIs in the JSON format. For YAML templates, you can also specify the specification in the YAML format.

Required: No"

The terminology differences between "OpenAPI specification" and "OpenAPI definition" are confusing me. I assume they're interchangeable, but I do not have any experience with API Gateway so I'm guessing. Hopefully one of you guys have come across this before & can clarify.

[markpeek]

The way I read it is, you can specify either Body or BodyS3Location to provide an OpenAPI spec which will then auto-name the API based on the title contents in the spec. (Using the API Gateway UI and playing with the Example API helps illustrate this). I'd say Name is required if neither of those are specified. It may also be possible (I haven't tested it) to use one of the Body/BodyS3Location and specify a Name. I would expect the Name property to take precedent but I don't know the answer to this question.

[churnikorn]

Maybe this helps: if you create a rest api resource via the template and provide a name, that name will be overwritten once the AWS importer is done if the title in the swagger file is not the same as the name. I'm not entirely sure where in the flow the check happens for AWS and if specifying a title in the swagger doc would be picked up during the resource creation to the apply to its name.