Configuring the Generator#

This document provides guidance on how to configure a code generator.

Introduction#

Smithy code generators are configured using plugins defined in smithy-build.json files. For example:

smithy-build.json#
{
    "version": "1.0",
    "plugins": {
        "foo-client-codegen": {
            "service": "smithy.example#Weather",
            "package": "com.example.weather",
            "edition": "2023"
        }
    }
}

How to name codegen plugins#

Smithy code generation plugins should use a naming pattern of <language>-<type>-codegen, where:

  • <language> is the name of the programming language
  • <type> is one of "client", "server", or "types"
  • codegen is the kind of plugin (in this case, a code generator)

Examples:

  • foo-client-codegen: generate a hypothetical Foo language client
  • foo-server-codegen: generate a hypothetical Foo language server

Converting JSON configuration to Java#

Configuration settings are parsed into generic "node" objects that Smithy-Build plugins can then deserialize into strongly typed Java records or POJOs. For example:

public final class FooCodegenSettings {
    private ShapeId service;
    private String packageName;
    private String edition;

    public ShapeId getService() {
        return service;
    }

    public void setService(ShapeId service) {
        this.service = service;
    }

    public String getPackage() {
        return packageName;
    }

    public void setPackage(String packageName) {
        this.packageName = packageName;
    }

    public void getEdition(String edition) {
        this.edition = edition;
    }

    public String setEdition() {
        return edition;
    }
}

You can use DirectedCodegen to easily wire up the POJO to your generator. Wiring up the configuration provided to the plugin to the generator can be done in SmithyBuildPlugin#execute using CodegenDirector#settings.

public final class FooCodegenPlugin implements SmithyBuildPlugin {
    @Override
    public String getName() {
        return "foo-client-codegen";
    }

    @Override
    public void execute(PluginContext context) {
        CodegenDirector<FooWriter, FooIntegration, FooContext, FooCodegenSettings>
                runner = new CodegenDirector<>();
        runner.directedCodegen(new DirectedFooCodegen());
        runner.settings(FooCodegenSettings.class, context.getSettings());
        // ...
        runner.run();
    }
}

See also