src

Go monorepo.
git clone git://code.dwrz.net/src
Log | Files | Refs

README.md (4597B)

      1 # Smithy Go
      2 
      3 [![Go Build Status](https://github.com/aws/smithy-go/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/aws/smithy-go/actions/workflows/go.yml)[![Codegen Build Status](https://github.com/aws/smithy-go/actions/workflows/codegen.yml/badge.svg?branch=main)](https://github.com/aws/smithy-go/actions/workflows/codegen.yml)
      4 
      5 [Smithy](https://smithy.io/) code generators for Go and the accompanying smithy-go runtime.
      6 
      7 The smithy-go runtime requires a minimum version of Go 1.23.
      8 
      9 **WARNING: All interfaces are subject to change.**
     10 
     11 ## :no_entry_sign: DO NOT use the code generators in this repository
     12 
     13 **The code generators in this repository do not generate working clients at
     14 this time.**
     15 
     16 In order to generate a usable smithy client you must provide a [protocol definition](https://github.com/aws/smithy-go/blob/main/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/integration/ProtocolGenerator.java),
     17 such as [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html),
     18 in order to generate transport mechanisms and serialization/deserialization
     19 code ("serde") accordingly.
     20 
     21 The code generator does not currently support any protocols out of the box.
     22 Support for all [AWS protocols](https://smithy.io/2.0/aws/protocols/index.html)
     23 exists in [aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2). We are
     24 tracking the movement of those out of the SDK into smithy-go in
     25 [#458](https://github.com/aws/smithy-go/issues/458), but there's currently no
     26 timeline for doing so.
     27 
     28 ## Plugins
     29 
     30 This repository implements the following Smithy build plugins:
     31 
     32 | ID | GAV prefix | Description |
     33 |----|------------|-------------|
     34 | `go-codegen`        | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go client code generation for Smithy models. |
     35 | `go-server-codegen` | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go server code generation for Smithy models. |
     36 | `go-shape-codegen` | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go shape code generation (types only) for Smithy models. |
     37 
     38 **NOTE: Build plugins are not currently published to mavenCentral. You must publish to mavenLocal to make the build plugins visible to the Smithy CLI. The artifact version is currently fixed at 0.1.0.**
     39 
     40 ## `go-codegen`
     41 
     42 ### Configuration
     43 
     44 [`GoSettings`](codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoSettings.java)
     45 contains all of the settings enabled from `smithy-build.json` and helper
     46 methods and types. The up-to-date list of top-level properties enabled for
     47 `go-client-codegen` can be found in `GoSettings::from()`.
     48 
     49 | Setting         | Type    | Required | Description                                                                                                                 |
     50 |-----------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------|
     51 | `service`       | string  | yes      | The Shape ID of the service for which to generate the client.                                                               |
     52 | `module`        | string  | yes      | Name of the module in `generated.json` (and `go.mod` if `generateGoMod` is enabled) and `doc.go`.                           |
     53 | `generateGoMod` | boolean |          | Whether to generate a default `go.mod` file. The default value is `false`.                                                  |
     54 | `goDirective`   | string  |          | [Go directive](https://go.dev/ref/mod#go-mod-file-go) of the module. The default value is the minimum supported Go version. |
     55 
     56 ### Supported protocols
     57 
     58 | Protocol | Notes |
     59 |----------|-------|
     60 | [`smithy.protocols#rpcv2Cbor`](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html) | Event streaming not yet implemented. |
     61 
     62 ### Example
     63 
     64 This example applies the `go-codegen` build plugin to the Smithy quickstart
     65 example created from `smithy init`:
     66 
     67 ```json
     68 {
     69   "version": "1.0",
     70   "sources": [
     71     "models"
     72   ],
     73   "maven": {
     74     "dependencies": [
     75       "software.amazon.smithy.go:smithy-go-codegen:0.1.0"
     76     ]
     77   },
     78   "plugins": {
     79     "go-codegen": {
     80       "service": "example.weather#Weather",
     81       "module": "github.com/example/weather",
     82       "generateGoMod": true,
     83       "goDirective": "1.23"
     84     }
     85   }
     86 }
     87 ```
     88 
     89 ## `go-server-codegen`
     90 
     91 This plugin is a work-in-progress and is currently undocumented.
     92 
     93 ## `go-shape-codegen`
     94 
     95 This plugin is a work-in-progress and is currently undocumented.
     96 
     97 ## License
     98 
     99 This project is licensed under the Apache-2.0 License.
    100