Skip to content

Commit cfc0beb

Browse files
author
luigi
committed
read me
1 parent e237145 commit cfc0beb

File tree

1 file changed

+116
-65
lines changed
  • codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service

1 file changed

+116
-65
lines changed

‎codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/README.md

Lines changed: 116 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -7,88 +7,135 @@ It produces **complete service stubs**—including routing, serialization/deseri
77

88
While Ktor is the default backend, the architecture is framework-agnostic, allowing future support for other server frameworks.
99

10-
### Key Features
11-
- **Automatic Service Stub Generation** from Smithy models
12-
- **Protocol Support**: CBOR & JSON
13-
- **Request Routing** generated from Smithy operations
14-
- **Authentication**: Bearer, SigV4, SigV4A
15-
- **Request Constraints & Validation** from Smithy traits
16-
- **Error Handling** with a consistent JSON/CBOR envelope
17-
- **Logging** with structured output for production readiness
18-
- **Extensible Architecture** for alternative frameworks
10+
---
11+
12+
## Feature Summary
13+
14+
| **Features** | **Description** |
15+
|---------------------------|-----------------|
16+
| Service Framework | Abstracted service framework interface and base implementation with Ktor as the default backend |
17+
| CBOR Protocol | Support for CBOR serialization / deserialization and CBOR protocol traits |
18+
| Json Protocol | Support for Json serialization / deserialization and Json protocol traits |
19+
| Routing | Per-operation routing generation with Ktor DSL; ties to handler and validation |
20+
| Error Handler | Unified exception handling logic mapped to HTTP status codes and support for error trait |
21+
| Authentication (bearer) | Bearer token authentication middleware with model-driven configuration |
22+
| Logging | Structured logging setup |
23+
| Constraints Checker | Validation logic generated from Smithy traits and invoked pre-handler |
24+
| Unit Test | Covers serialization/deserialization, routing, validation, and integration tests |
25+
26+
---
27+
28+
## Smithy Protocol Traits Support
29+
30+
| **Traits** | **CBOR Protocol** | **Json Protocol** |
31+
|--------------------------|-------------------|-------------------|
32+
| http | Yes | Yes |
33+
| httpError | Yes | Yes |
34+
| httpHeader | Not supported | Yes |
35+
| httpPrefixHeader | Not supported | Yes |
36+
| httpLabel | Not supported | Yes |
37+
| httpQuery | Not supported | Yes |
38+
| httpQueryParams | Not supported | Yes |
39+
| httpPayload | Not supported | Yes |
40+
| jsonName | Not supported | Yes |
41+
| timestampFormat | Not supported | Yes |
42+
| httpChecksumRequired | Not supported | Not implemented yet |
43+
| requestCompression | Not implemented yet | Not implemented yet |
44+
45+
---
46+
47+
## Constraint Traits Support
48+
49+
| **Traits** | **CBOR Protocol** | **Json Protocol** |
50+
|-----------------|------------------------------|------------------------------|
51+
| required | Yes | Yes |
52+
| length | Yes | Yes |
53+
| pattern | Yes | Yes |
54+
| private | Yes (handled by Smithy) | Yes (handled by Smithy) |
55+
| range | Yes | Yes |
56+
| uniqueItems | Yes | Yes |
57+
| idRef | Not implemented yet | Not implemented yet |
1958

2059
---
2160

2261
## Getting Started
2362

24-
### 1. Build & Publish to Local Maven
25-
From the project root, run:
63+
### Step 1: Build & Publish Codegen to Local Maven
64+
First, in **this repository**, build and publish the code generator locally:
2665
```bash
2766
./gradlew :codegen:smithy-kotlin-codegen:build
2867
./gradlew publishToMavenLocal
2968
```
3069

3170
---
3271

33-
### 2. Create a New Kotlin Project
72+
### Step 2: Create a New Kotlin Project
73+
Now, create a **new Kotlin project** where you will use the Smithy Kotlin service code generator.
74+
75+
From this point forward, **all steps apply to the new Kotlin project** you just created.
3476

35-
In your **`build.gradle.kts`**:
77+
---
78+
79+
### Step 3: Configure `build.gradle.kts` in the New Project
3680

3781
```kotlin
3882
plugins {
39-
id("software.amazon.smithy.gradle.smithy-jar") version "1.3.0" // check for latest version
83+
alias(libs.plugins.kotlin.jvm)
84+
id("software.amazon.smithy.gradle.smithy-jar") version "1.3.0" // check for latest version
85+
application
4086
}
4187

4288
repositories {
43-
mavenLocal()
44-
mavenCentral()
89+
mavenLocal()
90+
mavenCentral()
4591
}
4692

4793
dependencies {
48-
smithyBuild("software.amazon.smithy.kotlin:smithy-kotlin-codegen:<codegenVersion>")
49-
implementation("software.amazon.smithy.kotlin:smithy-aws-kotlin-codegen:<codegenVersion>")
50-
implementation("software.amazon.smithy:smithy-model:<smithyVersion>")
51-
implementation("software.amazon.smithy:smithy-build:<smithyVersion>")
52-
implementation("software.amazon.smithy:smithy-aws-traits:<smithyVersion>")
94+
smithyBuild("software.amazon.smithy.kotlin:smithy-kotlin-codegen:<codegenVersion>")
95+
implementation("software.amazon.smithy.kotlin:smithy-aws-kotlin-codegen:<codegenVersion>")
96+
implementation("software.amazon.smithy:smithy-model:<smithyVersion>")
97+
implementation("software.amazon.smithy:smithy-build:<smithyVersion>")
98+
implementation("software.amazon.smithy:smithy-aws-traits:<smithyVersion>")
99+
...
53100
}
54101
```
55102

56103
---
57104

58-
### 3. Configure Smithy Build
59-
60-
Create `smithy-build.json` in the same directory as `build.gradle.kts`:
61-
105+
### Step 4: Create `smithy-build.json` in the New Project
106+
This is an example of smithy-build.json.
62107
```json
63108
{
64-
"version": "1.0",
65-
"outputDirectory": "build/generated-src",
66-
"plugins": {
67-
"kotlin-codegen": {
68-
"service": "com.demo#DemoService",
69-
"package": {
70-
"name": "com.demo.server",
71-
"version": "1.0.0"
72-
},
73-
"build": {
74-
"rootProject": true,
75-
"generateServiceProject": true,
76-
"optInAnnotations": [
77-
"aws.smithy.kotlin.runtime.InternalApi",
78-
"kotlinx.serialization.ExperimentalSerializationApi"
79-
]
80-
},
81-
"serviceStub": {
82-
"framework": "ktor"
83-
}
84-
}
85-
}
109+
"version": "1.0",
110+
"outputDirectory": "build/generated-src", // define the output path
111+
"plugins": {
112+
"kotlin-codegen": {
113+
// change based on smithy model <namespace>#<service shape name>
114+
"service": "com.demo#DemoService",
115+
"package": {
116+
"name": "com.demo.server",
117+
"version": "1.0.0"
118+
},
119+
"build": {
120+
"rootProject": true,
121+
"generateServiceProject": true,
122+
"optInAnnotations": [
123+
"aws.smithy.kotlin.runtime.InternalApi",
124+
"kotlinx.serialization.ExperimentalSerializationApi"
125+
]
126+
},
127+
"serviceStub": {
128+
// choose server framework, only ktor is supported now
129+
"framework": "ktor"
130+
}
131+
}
132+
}
86133
}
87134
```
88135

89136
---
90137

91-
### 4. Define Your Smithy Model
138+
### Step 5: Define Your Smithy Model in the New Project
92139

93140
Create a `model` directory and add your `.smithy` files.
94141
Example `model/greeter.smithy`:
@@ -103,43 +150,47 @@ use smithy.api#httpBearerAuth
103150
@restJson1
104151
@httpBearerAuth
105152
service DemoService {
106-
version: "1.0.0"
107-
operations: [SayHello]
153+
version: "1.0.0"
154+
operations: [
155+
SayHello
156+
]
108157
}
109158
110159
@http(method: "POST", uri: "/greet", code: 201)
111160
operation SayHello {
112-
input: SayHelloInput
113-
output: SayHelloOutput
114-
errors: [CustomError]
161+
input: SayHelloInput
162+
output: SayHelloOutput
163+
errors: [
164+
CustomError
165+
]
115166
}
116167
117168
@input
118169
structure SayHelloInput {
119-
@required
120-
@length(min: 3, max: 10)
121-
name: String
122-
@httpHeader("X-User-ID")
123-
id: Integer
170+
@required
171+
@length(min: 3, max: 10)
172+
name: String
173+
@httpHeader("X-User-ID")
174+
id: Integer
124175
}
125176
126177
@output
127178
structure SayHelloOutput {
128-
greeting: String
179+
greeting: String
129180
}
130181
131182
@error("server")
132183
@httpError(500)
133184
structure CustomError {
134-
msg: String
135-
@httpHeader("X-User-error")
136-
err: String
185+
msg: String
186+
@httpHeader("X-User-error")
187+
err: String
137188
}
138189
```
139190

140191
---
141192

142-
### 5. Generate the Service
193+
### Step 6: Generate the Service in the New Project
143194

144195
Run:
145196
```bash
@@ -153,7 +204,7 @@ gradle clean
153204

154205
---
155206

156-
### 6. Run the Service
207+
### Step 7: Run the Generated Service
157208

158209
The generated service will be in the directory specified in `smithy-build.json` (`outputDirectory`).
159210
You can start it by running:
@@ -164,7 +215,7 @@ By default, it listens on port **8080**.
164215

165216
---
166217

167-
### 7. Adjust Service Configuration
218+
### Step 8: Adjust Service Configuration
168219

169220
You can override runtime settings (such as port or HTTP engine) using command-line arguments:
170221
```bash

0 commit comments

Comments
 (0)