src

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

README.md (4657B)

      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.24.
      8 
      9 **WARNING: All interfaces are subject to change.**
     10 
     11 ## :warning: Client codegen is unstable
     12 
     13 The client code generator in this repository powers the aws-sdk-go-v2.
     14 Arbitrary client generation, while possible, is in an early stage of
     15 development:
     16 
     17 * Generated clients are missing certain features that were originally
     18   implemented SDK-side (e.g. retries)
     19 * There may be bugs
     20 * The public APIs of generated clients may be unstable
     21 
     22 If you are interested in using the client code generators, we encourage you to
     23 experiment and share any feedback with us in an issue.
     24 
     25 ## Plugins
     26 
     27 This repository implements the following Smithy build plugins:
     28 
     29 | ID | GAV prefix | Description |
     30 |----|------------|-------------|
     31 | `go-codegen`        | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go client code generation for Smithy models. |
     32 | `go-server-codegen` | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go server code generation for Smithy models. |
     33 | `go-shape-codegen` | `software.amazon.smithy.go:smithy-go-codegen` | Implements Go shape code generation (types only) for Smithy models. |
     34 
     35 ## `go-codegen`
     36 
     37 ### Configuration
     38 
     39 [`GoSettings`](codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoSettings.java)
     40 contains all of the settings enabled from `smithy-build.json` and helper
     41 methods and types. The up-to-date list of top-level properties enabled for
     42 `go-client-codegen` can be found in `GoSettings::from()`.
     43 
     44 | Setting         | Type    | Required | Description                                                                                                                 |
     45 |-----------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------|
     46 | `service`       | string  | yes      | The Shape ID of the service for which to generate the client.                                                               |
     47 | `module`        | string  | yes      | Name of the module in `generated.json` (and `go.mod` if `generateGoMod` is enabled) and `doc.go`.                           |
     48 | `generateGoMod` | boolean |          | Whether to generate a default `go.mod` file. The default value is `false`.                                                  |
     49 | `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. |
     50 
     51 ### Supported protocols
     52 
     53 The protocol a client uses is configured by the `Protocol` field on a client's
     54 `Options`. The SDK will configure a default based on the protocol traits
     55 applied to the modeled service.
     56 
     57 | Protocol | Notes |
     58 |----------|-------|
     59 | [`smithy.protocols#rpcv2Cbor`](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html) | |
     60 | [`aws.protocols#restJson1`](https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html) | |
     61 | [`aws.protocols#restXml`](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html) | |
     62 | [`aws.protocols#awsJson1_0`](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html) | |
     63 | [`aws.protocols#awsJson1_1`](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html) | |
     64 | [`aws.protocols#awsQuery`](https://smithy.io/2.0/aws/protocols/aws-query-protocol.html) | |
     65 | [`aws.protocols#ec2Query`](https://smithy.io/2.0/aws/protocols/aws-ec2-query-protocol.html) | |
     66 
     67 ### Example
     68 
     69 This example applies the `go-codegen` build plugin to the Smithy quickstart
     70 example created from `smithy init`:
     71 
     72 ```json
     73 {
     74   "version": "1.0",
     75   "sources": [
     76     "models"
     77   ],
     78   "maven": {
     79     "dependencies": [
     80       "software.amazon.smithy.go:smithy-go-codegen:[0.1.0,2.0)"
     81     ]
     82   },
     83   "plugins": {
     84     "go-codegen": {
     85       "service": "example.weather#Weather",
     86       "module": "github.com/example/weather",
     87       "generateGoMod": true,
     88       "goDirective": "1.24"
     89     }
     90   }
     91 }
     92 ```
     93 
     94 ## `go-server-codegen`
     95 
     96 This plugin is a work-in-progress and is currently undocumented.
     97 
     98 ## `go-shape-codegen`
     99 
    100 This plugin is a work-in-progress and is currently undocumented.
    101 
    102 ## License
    103 
    104 This project is licensed under the Apache-2.0 License.
    105