From 83190ba6fccbc8117b4b9b2d961b4c6fee0fab48 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Tue, 26 Apr 2022 16:06:41 +0200 Subject: [PATCH] Fill out documentation in aws traits --- .../META-INF/smithy/aws.apigateway.smithy | 78 +++++++++++++++++- .../resources/META-INF/smithy/aws.api.smithy | 81 ++++++++++++++++++- .../META-INF/smithy/aws.protocols.smithy | 29 ++++++- 3 files changed, 181 insertions(+), 7 deletions(-) diff --git a/smithy-aws-apigateway-traits/src/main/resources/META-INF/smithy/aws.apigateway.smithy b/smithy-aws-apigateway-traits/src/main/resources/META-INF/smithy/aws.apigateway.smithy index deaf640350f..9a7f52474d5 100644 --- a/smithy-aws-apigateway-traits/src/main/resources/META-INF/smithy/aws.apigateway.smithy +++ b/smithy-aws-apigateway-traits/src/main/resources/META-INF/smithy/aws.apigateway.smithy @@ -40,37 +40,67 @@ map authorizers { ] ) structure integration { + /// The type of integration with the specified backend. @required type: IntegrationType + /// 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. @required uri: Arn + /// Specifies the credentials required for the integration, if any. For AWS + /// IAM role-based credentials, specify the ARN of an appropriate IAM role. + /// If unspecified, credentials will default to resource-based permissions + /// that must be added manually to allow the API to access the resource. credentials: IamRoleArn + /// Specifies the integration's HTTP method type (for example, `POST`). + /// For Lambda function invocations, the value must be `POST`. @required httpMethod: String + /// Specifies how a request payload of unmapped content type is passed + /// through the integration request without modification. passThroughBehavior: PassThroughBehavior + /// Request payload content handling. contentHandling: ContentHandling + /// Integration timeouts between 50 ms and 29,000 ms. timeoutInMillis: Integer + /// The ID of a VpcLink for the private integration. connectionId: String + /// The type of the network connection to the integration endpoint. The + /// valid value is `INTERNET` for connections through the public routable + /// internet or `VPC_LINK` for private connections between API Gateway and + /// a network load balancer in a VPC. The default value is `INTERNET`. connectionType: ConnectionType + /// An API-specific tag group of related cached parameters. cacheNamespace: String + /// Specifies the format of the payload sent to an integration. Required + /// for HTTP APIs. For HTTP APIs, supported values for Lambda proxy + /// integrations are 1.0 and 2.0. For all other integrations, 1.0 is the + /// only supported value. payloadFormatVersion: String + /// A list of request parameter names whose values are to be cached. cacheKeyParameters: StringList + /// Specifies mappings from method request parameters to integration + /// request parameters. requestParameters: RequestParameters + /// Mapping templates for a request payload of specified media types. requestTemplates: Templates + /// Defines the method's responses and specifies desired parameter mappings + /// or payload mappings from integration responses to method responses. responses: IntegrationResponses } @@ -84,12 +114,19 @@ structure integration { ] ) structure mockIntegration { + /// Specifies how a request payload of unmapped content type is passed + /// through the integration request without modification. passThroughBehavior: PassThroughBehavior + /// Specifies mappings from method request parameters to integration + /// request parameters. requestParameters: RequestParameters + /// Mapping templates for a request payload of specified media types. requestTemplates: Templates + /// Defines the method's responses and specifies desired parameter mappings + /// or payload mappings from integration responses to method responses. responses: IntegrationResponses } @@ -149,8 +186,17 @@ structure IntegrationResponse { /// correspond to a matching response in the OpenAPI Operation responses /// field. statusCode: String + + /// Response payload content handling. contentHandling: ContentHandling + + /// Specifies media type-specific mapping templates for the response's + /// payload. responseTemplates: Templates + + /// 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. responseParameters: ResponseParameters } @@ -217,14 +263,24 @@ map Templates { string Arn enum ConnectionType { + /// Connections through the public routable internet. INTERNET + + /// Private connections between API Gateway and a network load balancer in + /// a VPC. VPC_LINK } -/// Defines the contentHandling for the integration +/// Defines the contentHandling for the integration. @private enum ContentHandling { + /// 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 CONVERT_TO_TEXT + + /// For converting a text payload into Base64-decoded blob or passing + /// through a binary payload natively without modification. CONVERT_TO_BINARY } @@ -239,15 +295,21 @@ enum ContentHandling { string IamRoleArn enum IntegrationType { + /// An integration with AWS Lambda functions or other AWS services such as + /// Amazon DynamoDB, Amazon Simple Notification Service or Amazon Simple + /// Queue Service. @enumValue("aws") AWS + /// An integration with AWS Lambda functions. @enumValue("aws_proxy") AWS_PROXY + /// An integration with an HTTP backend. @enumValue("http") HTTP + /// An integration with an HTTP backend. @enumValue("http_proxy") HTTP_PROXY } @@ -255,12 +317,26 @@ enum IntegrationType { /// Defines the passThroughBehavior for the integration @private enum PassThroughBehavior { + /// Passes the method request body through the integration request to the + /// back end without transformation when no mapping template is defined in + /// the integration request. If a template is defined when this option is + /// selected, the method request of an unmapped content-type will be + /// rejected with an HTTP 415 Unsupported Media Type response. @enumValue("when_no_templates") WHEN_NO_TEMPLATES + /// Passes the method request body through the integration request to the + /// back end without transformation when the method request content type + /// does not match any content type associated with the mapping templates + /// defined in the integration request. @enumValue("when_no_match") WHEN_NO_MATCH + /// Rejects the method request with an HTTP 415 Unsupported Media Type + /// response when either the method request content type does not match any + /// content type associated with the mapping templates defined in the + /// integration request or no mapping template is defined in the integration + /// request. @enumValue("never") NEVER } diff --git a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.api.smithy b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.api.smithy index 07876316f66..f75cdea5be7 100644 --- a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.api.smithy +++ b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.api.smithy @@ -8,20 +8,57 @@ namespace aws.api ) @trait(selector: "resource") structure arn { + /// Defines the ARN template. The provided string contains URI-template + /// style label placeholders that contain the name of one of the identifiers + /// defined in the `identifiers` property of the resource. These labels can + /// be substituted at runtime with the actual identifiers of the resource. + /// Every identifier name of the resource MUST have corresponding label of + /// the same name. Note that percent-encoding **is not** performed on these + /// placeholder values; they are to be replaced literally. For relative ARN + /// templates that have not set `absolute` to `true`, the template string + /// contains only the resource part of the ARN (for example, + /// `foo/{MyResourceId}`). Relative ARNs MUST NOT start with "/". @required template: String + + /// Set to true to indicate that the ARN template contains a fully-formed + /// ARN that does not need to be merged with the service. This type of ARN + /// MUST be used when the identifier of a resource is an ARN or is based on + /// the ARN identifier of a parent resource. absolute: Boolean + + /// Set to true to specify that the ARN does not contain a region. If not + /// set, or if set to false, the resolved ARN will contain a placeholder + /// for the region. This can only be set to true if `absolute` is not set + /// or is false. noRegion: Boolean + + /// Set to true to specify that the ARN does not contain an account ID. If + /// not set, or if set to false, the resolved ARN will contain a placeholder + /// for the customer account ID. This can only be set to true if absolute + /// is not set or is false. noAccount: Boolean } /// Marks a string as containing an ARN. -@trait( - selector: "string" -) +@trait(selector: "string") structure arnReference { + /// The AWS CloudFormation resource type contained in the ARN. type: String + + /// An absolute shape ID that references the Smithy resource type contained + /// in the ARN (e.g., `com.foo#SomeResource`). The targeted resource is not + /// required to be found in the model, allowing for external shapes to be + /// referenced without needing to take on an additional dependency. If the + /// shape is found in the model, it MUST target a resource shape, and the + /// resource MUST be found within the closure of the referenced service + /// shape. resource: String + + /// The Smithy service absolute shape ID that is referenced by the ARN. The + /// targeted service is not required to be found in the model, allowing for + /// external shapes to be referenced without needing to take on an + /// additional dependency. service: String } @@ -29,6 +66,11 @@ structure arnReference { /// discovery logic. @trait(selector: "operation") structure clientDiscoveredEndpoint { + /// This field denotes whether or not this operation requires the use of a + /// specific endpoint. If this field is false, the standard regional + /// endpoint for a service can handle this request. The client will start + /// sending requests to the standard regional endpoint while working to + /// discover a more specific endpoint. @required required: Boolean } @@ -127,24 +169,57 @@ enum data { ) structure dataPlane {} +/// An AWS service is defined using the `aws.api#service` trait. This trait +/// provides information about the service like the name used to generate AWS +/// SDK client classes and the namespace used in ARNs. @trait(selector: "service") structure service { + /// The `sdkId` property is a required string value that specifies the AWS + /// SDK service ID (e.g., "API Gateway"). This value is used for generating + /// client names in SDKs and for linking between services. @required sdkId: String + /// The `arnNamespace` property is a string value that defines the ARN service + /// namespace of the service (e.g., "apigateway"). This value is used in + /// ARNs assigned to resources in the service. If not set, this value + /// defaults to the lowercase name of the service shape. arnNamespace: ArnNamespace + /// The `cloudFormationName` property is a string value that specifies the + /// AWS CloudFormation service name (e.g., `ApiGateway`). When not set, + /// this value defaults to the name of the service shape. This value is + /// part of the CloudFormation resource type name that is automatically + /// assigned to resources in the service (e.g., `AWS::::resourceName`). cloudFormationName: CloudFormationName + /// The `cloudTrailEventSource` property is a string value that defines the + /// AWS customer-facing eventSource property contained in CloudTrail event + /// records emitted by the service. If not specified, this value defaults + /// to the `arnNamespace` plus `.amazonaws.com`. cloudTrailEventSource: String + /// The `endpointPrefix` property is a string value that identifies which + /// endpoint in a given region should be used to connect to the service. + /// For example, most services in the AWS standard partition have endpoints + /// which follow the format: `{endpointPrefix}.{region}.amazonaws.com`. A + /// service with the endpoint prefix example in the region us-west-2 might + /// have the endpoint example.us-west-2.amazonaws.com. + /// + /// This value is not unique across services and is subject to change. + /// Therefore, it MUST NOT be used for client naming or for any other + /// purpose that requires a static, unique identifier. sdkId should be used + /// for those purposes. Additionally, this value can be used to attempt to + /// resolve endpoints. endpointPrefix: String } +/// A string representing a service's ARN namespace. @pattern("^[a-z0-9.\\-]{1,63}$") @private string ArnNamespace +/// A string representing a CloudFormation service name. @pattern("^[A-Z][A-Za-z0-9]+$") @private string CloudFormationName diff --git a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.protocols.smithy b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.protocols.smithy index 712747f3f77..b18dd30e8a3 100644 --- a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.protocols.smithy +++ b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.protocols.smithy @@ -15,8 +15,13 @@ namespace aws.protocols ) @trait(selector: "service") structure awsJson1_0 { + /// The priority ordered list of supported HTTP protocol versions. http: StringList + /// The priority ordered list of supported HTTP protocol versions that + /// are required when using event streams with the service. If not set, + /// this value defaults to the value of the `http` member. Any entry in + /// `eventStreamHttp` MUST also appear in `http`. eventStreamHttp: StringList } @@ -35,7 +40,13 @@ structure awsJson1_0 { selector: "service" ) structure awsJson1_1 { + /// The priority ordered list of supported HTTP protocol versions. http: StringList + + /// The priority ordered list of supported HTTP protocol versions that + /// are required when using event streams with the service. If not set, + /// this value defaults to the value of the `http` member. Any entry in + /// `eventStreamHttp` MUST also appear in `http`. eventStreamHttp: StringList } @@ -104,9 +115,7 @@ structure ec2Query {} string ec2QueryName /// Indicates that an operation supports checksum validation. -@trait( - selector: "operation" -) +@trait(selector: "operation") @unstable structure httpChecksum { /// Defines a top-level operation input member that is used to configure @@ -146,8 +155,13 @@ structure httpChecksum { ) @trait(selector: "service") structure restJson1 { + /// The priority ordered list of supported HTTP protocol versions. http: StringList + /// The priority ordered list of supported HTTP protocol versions that + /// are required when using event streams with the service. If not set, + /// this value defaults to the value of the `http` member. Any entry in + /// `eventStreamHttp` MUST also appear in `http`. eventStreamHttp: StringList } @@ -176,8 +190,13 @@ structure restJson1 { ) @trait(selector: "service") structure restXml { + /// The priority ordered list of supported HTTP protocol versions. http: StringList + /// The priority ordered list of supported HTTP protocol versions that + /// are required when using event streams with the service. If not set, + /// this value defaults to the value of the `http` member. Any entry in + /// `eventStreamHttp` MUST also appear in `http`. eventStreamHttp: StringList /// Disables the serialization wrapping of error properties in an 'Error' @@ -199,11 +218,15 @@ set ChecksumAlgorithmSet { @private enum ChecksumAlgorithm { + /// CRC32C CRC32C + /// CRC32 CRC32 + /// SHA1 SHA1 + /// SHA256 SHA256 }