Enable general client generation from smithy models

build.gradle.kts

@@ -8,8 +8,6 @@ plugins {
     id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
 }
 
-group = "aws.sdk.kotlin"
-
 dependencies {
     dokkaPlugin(project(":dokka-aws"))
 }
@@ -82,9 +80,16 @@ tasks.dokkaHtmlMultiModule {
     removeChildTasks(excludeFromDocumentation)
 }
 
-if (project.hasProperty("sonatypeUsername") && project.hasProperty("sonatypePassword")) {
+if (
+    project.hasProperty("sonatypeUsername") &&
+    project.hasProperty("sonatypePassword") &&
+    project.hasProperty("publishGroupName")
+) {
     apply(plugin = "io.github.gradle-nexus.publish-plugin")
 
+    val publishGroupName = project.property("publishGroupName") as String
+    group = publishGroupName
+
     nexusPublishing {
         repositories {
             create("awsNexus") {

codegen/smithy-aws-kotlin-codegen/build.gradle.kts

@@ -5,6 +5,7 @@
 plugins {
     kotlin("jvm")
     jacoco
+    `maven-publish`
 }
 
 val sdkVersion: String by project
@@ -93,3 +94,26 @@ tasks.jacocoTestReport {
 
 // Always run the jacoco test report after testing.
 tasks["test"].finalizedBy(tasks["jacocoTestReport"])
+
+val sourcesJar by tasks.creating(Jar::class) {
+    group = "publishing"
+    description = "Assembles Kotlin sources jar"
+    classifier = "sources"
+    from(sourceSets.getByName("main").allSource)
+}
+
+if (
+    !project.hasProperty("publishGroupName") ||
+    group.toString().startsWith(project.property("publishGroupName") as String)
+) {
+    publishing {
+        publications {
+            create<MavenPublication>("codegen") {
+                from(components["java"])
+                artifact(sourcesJar)
+            }
+        }
+    }
+
+    apply(from = rootProject.file("gradle/publish.gradle"))
+}

docs/howto/client-generator.md

@@ -0,0 +1,64 @@
+# Generating a Kotlin Client from a Smithy Model
+
+## Overview
+
+This page covers how to generate a Kotlin client from any valid Smithy model.  This generated Kotlin client could then be used to interact with a service instance from a Kotlin program.  The Kotlin codegen is under active development and there remains several details that must be implemented before this approach can be used to create a fully functional client.  However, using the code generator can give insights into how API models translate into working Kotlin code that service customers may interact with in the future.
+
+### Limitations
+
+* The generated project requires some additions to the Gradle build file in order to successfully build the project (covered below).
+* AWS-specific logic will be included in the generated client that should be disregarded.  In a future release this will be fixed.  For now please ignore AWS specific logic such as AWS regions.
+* You'll need to include all model dependencies directly in a local project.
+
+### Prerequisites
+
+* Intellij IDE installed locally
+* Kotlin AWS SDK installed locally (local maven repo)
+* A valid Smithy model
+
+## Steps
+
+The following steps will create a project that will codegen a client when built. Either follow these steps or check out the example provided in `/examples/client-generator`.
+
+1. Create a new Intellij Kotlin project, accepting defaults.
+2. Add the following lines to the already generated Gradle `build.gradle.kts` file:
+   ```kotlin
+   plugins {
+      ...
+      id("software.amazon.smithy").version("0.5.3")
+   }
+   ```
+   ```kotlin
+   dependencies {
+       ...
+       // NOTE: More smithy dependencies may be required depending on what's referenced by your API models.
+       implementation("software.amazon.smithy.kotlin:smithy-aws-kotlin-codegen:<latest version>")
+   }
+   ```
+3. Add your model file(s) into a new directory at the root of your project called `model`.
+   1. Add a `smithy-build.json` file into the root of your project.  Substitute `<namespace>`, `<service-name>`, and `<version>` for literals from your model and service:
+      ```json
+      {
+           "version": "1.0",
+           "plugins": {
+               "kotlin-codegen": {
+               "service": "<namespace>#<service-name>",
+               "package": {
+                   "name": "<namespace>",
+                   "version": "<version>",
+                   "description": "<service-name>"
+               },
+               "sdkId": "<service-name>",
+               "build": {
+                   "generateDefaultBuildFiles": true,
+                   "optInAnnotations": [
+                       "aws.smithy.kotlin.runtime.util.InternalApi",
+                       "aws.sdk.kotlin.runtime.InternalSdkApi"
+                   ],
+                   "rootProject": true
+               }
+           }}
+      }
+      ```
+4. Run the `build` Gradle task to generate the service client.
+5. Look in `build/smithyprojections/<project name>/source/kotlin-codegen` for a generated Gradle project of the Kotlin client.

examples/build.gradle.kts

@@ -1,18 +1,13 @@
 plugins {
-    kotlin("jvm") version "1.5.0"
+    kotlin("jvm") version "1.5.20"
 }
 
 allprojects {
     group = "aws.sdk.kotlin.example"
-    version = "0.3.0-SNAPSHOT"
+    version = "0.4.0-SNAPSHOT"
 
     repositories {
-        maven {
-            name = "kotlinSdkLocal"
-            url = uri(TODO("set your local repository path"))
-            // e.g.
-            //url = uri("file:///tmp/aws-sdk-kotlin-repo/m2")
-        }
+        mavenLocal()
         mavenCentral()
     }
 }

examples/client-generator/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    kotlin("jvm")
+    id("software.amazon.smithy").version("0.5.3")
+}
+
+val awsSdkKotlinVersion: String by project
+
+dependencies {
+    implementation("software.amazon.smithy.kotlin:smithy-aws-kotlin-codegen:$awsSdkKotlinVersion")
+    // NOTE: More smithy dependencies may be required depending on what's referenced by your API models.
+}

examples/client-generator/model/weather-service.smithy

@@ -0,0 +1,111 @@
+namespace example.weather
+
+use aws.protocols#awsJson1_0
+use aws.api#service
+
+@service(sdkId: "Weather")
+@awsJson1_0
+service Weather {
+  version: "2006-03-01",
+  resources: [City],
+  operations: [GetCurrentTime]
+}
+
+resource City {
+  identifiers: { cityId: CityId },
+  read: GetCity,
+  list: ListCities,
+  resources: [Forecast]
+}
+
+resource Forecast {
+  identifiers: { cityId: CityId },
+  read: GetForecast
+}
+
+// Pattern is a trait.
+@pattern("^[A-Za-z0-9 ]+$")
+string CityId
+
+@readonly
+operation GetCurrentTime {
+    output: GetCurrentTimeOutput
+}
+
+structure GetCurrentTimeOutput {
+  time: smithy.api#Timestamp
+}
+
+@readonly
+operation GetForecast {
+    input: GetForecastInput,
+    output: GetForecastOutput,
+    errors: [NoSuchResource]
+}
+
+structure GetForecastInput {
+  @required cityId: CityId
+}
+
+structure GetForecastOutput {
+  @required chanceOfRain: smithy.api#Float,
+  @required low: smithy.api#Integer,
+  @required high: smithy.api#Integer
+}
+
+@readonly
+operation GetCity {
+    input: GetCityInput,
+    output: GetCityOutput,
+    errors: [NoSuchResource]
+}
+
+structure GetCityInput {
+  @required cityId: CityId
+}
+
+structure GetCityOutput {
+  @required name: smithy.api#String,
+  @required coordinates: CityCoordinates
+}
+
+@readonly
+@paginated(inputToken: "nextToken", outputToken: "nextToken",
+           pageSize: "pageSize", items: "items")
+operation ListCities {
+    input: ListCitiesInput,
+    output: ListCitiesOutput
+}
+
+structure ListCitiesInput {
+  nextToken: smithy.api#String,
+  pageSize: smithy.api#Integer
+}
+
+// Traits can be applied outside of the definition.
+apply ListCitiesInput @documentation("hello!")
+
+structure ListCitiesOutput {
+  nextToken: smithy.api#String,
+  @required items: CitySummaries
+}
+
+structure CityCoordinates {
+  @required latitude: smithy.api#Float,
+  @required longitude: smithy.api#Float
+}
+
+@error("client")
+structure NoSuchResource {
+  @required resourceType: smithy.api#String
+}
+
+list CitySummaries {
+  member: CitySummary
+}
+
+@references([{resource: City}])
+structure CitySummary {
+  @required cityId: CityId,
+  @required name: smithy.api#String
+}

examples/client-generator/smithy-build.json

@@ -0,0 +1,21 @@
+{
+  "version": "1.0",
+  "plugins": {
+    "kotlin-codegen": {
+      "service": "example.weather#Weather",
+      "package": {
+        "name": "example.weather",
+        "version": "0.1.0",
+        "description": "Weather"
+      },
+      "sdkId": "Weather",
+      "build": {
+        "generateDefaultBuildFiles": true,
+        "optInAnnotations": [
+          "aws.smithy.kotlin.runtime.util.InternalApi",
+          "aws.sdk.kotlin.runtime.InternalSdkApi"
+        ],
+        "rootProject": true
+      }
+    }}
+}

examples/settings.gradle.kts

@@ -1,4 +1,5 @@
 rootProject.name = "aws-sdk-kotlin-examples"
 
+include(":client-generator")
 include(":dynamodb-movies")
 include(":s3-media-ingestion")