Skip to content

TypeSpec Go QuickStart

Jump to bottom
JiaqiZhang-Dev edited this page Mar 7, 2025 · 5 revisions

Before you Start

Go Azure SDK Design Guidelines is the overall design guideline of sdk. Make sure you are familiar with concepts such as "ServiceClient" and "Packages".

Make sure you are familiar with Git and Go Packages.

Generate SDK

Step 1: Clarify your module folder in SDK repository

Namespace is decided by SDK arch board.

For service, it is usually your service name in REST API specifications. For instance, if the TypeSpec is under specification/storage, the service would normally be storage.

For package, please refer to Azure SDK Module Design in Go Guideline. For example, if the service name is storage, the package should be armstorage or azstorage.(Use arm for management-plane packages, and az for all other packages.)

After service and module, the output-dir would be <sdk-repository-dir>/sdk/<service>/<module>. This is where the SDK code should be generated when you call npx tsp compile.

Step 2: TypeSpec configuration

☑️ It is recommended to configure TypeSpec package on REST API specifications. Please refer to these guidelines.

💡Particularly, here are templates for management plane and data plane service, you can use these templates:

Go specific options for tspconfig.yaml

☑️ Please make sure service-dir, package-dir, module (for typespec-go) is correctly configured.

  • service-dir: Default as sdk/<service>. If your service is a management-plane service, like specification/azurefleet/AzureFleet.Management, the service dir needs to be sdk/resourcemanager/computefleet.
  • package-dir: Default as <package>.
  • module: Default as "github.com/Azure/azure-sdk-for-go/{service-dir}/{package-dir}".
  • module-version: Semantic version of the Go module(e.g. 1.2.3).
  • fix-const-stuttering: Default as true. Fix stuttering for const types and values.
  • flavor: Default as azure for azure service.
  • generate-samples: Default as true. Generates sample codes with the SDK..
  • generate-fakes: Default as true. Generates test codes with the SDK..
  • head-as-boolean: Default as true. HEAD requests will return a boolean value based on the HTTP status code.
  • inject-spans: Default as true. Enables generation of spans for distributed tracing.
  • factory-gather-all-params: Default as false. The NewClientFactory constructor gathers all parameters or only common parameters of clients.
  • azcore-version: Semantic version of azcore without the leading 'v' to use if different from the default version (e.g. 1.2.3).
  • disallow-unknown-fields: Default as false. When true, unmarshalers will return an error when an unknown field is encountered in the payload.
  • file-prefix: Optional prefix to file names. For example, if you set your file prefix to "zzz_", all generated code files will begin with "zzz_".
  • rawjson-as-bytes: Default as false. When true, properties that are untyped (i.e. raw JSON) are exposed as []byte instead of any or map[string]any. The default is false.
  • slice-elements-byval: Default as false. When true, slice elements will not be pointer-to-type.
  • single-client: Indicates package has a single client. This will omit the Client prefix from options and response types. If multiple clients are detected, an error is returned. The default is false.
  • stutter: Uses the specified value to remove stuttering from types and funcs instead of the built-in algorithm.
  • fix-const-stuttering: Default as false. When true, fix stuttering for const types and values.

Step 3: Generate SDK

Option 1: Use SDK Automation from REST API specifications

After configuration is completed, making a draft pull request on azure-rest-api-specs repository would automatically trigger SDK generation for all configured SDKs. The automation will create new pull request on azure-sdk-for-go repository. One can fork it for further development.

Option 2: Use tsp-client to generate sdk locally

Configuration

You can refer to the tsp-location.yaml which describes the supported properties in the file. You can update tsp-location.yaml under SDK project folder to track the TypeSpec project.

Generate Code

SDK will be generated under the SDK project folder of azure-sdk-for-go. With tsp-location.yaml ready, run the following tsp-client command from project directory (i.e. your current directory is <sdk-repository-dir>/sdk/<service>/<module>) to generate the code: :ballot_box_with_check: tsp-client can be installed globally via npm install -g @azure-tools/typespec-client-generator-cli.

tsp-client update

The version of TypeSpec-Go is configured in emitter-package.json. Change it in local, if you would like to use a different version of typespec-go.

If you would like to test with locally modified TypeSpec, invoke tsp-client update with --save-inputs option. This tells the command not to delete the "TempTypeSpecFiles" folder, therefore you can modify the TypeSpec and then run tsp-client generate --save-inputs. Remember that all changes in "TempTypeSpecFiles" folder would be temporary.

Clone this wiki locally