Configure Code Generation

Understanding apex configuration

An apex configuration is YAML that defines which files are generated and by which module. The structure of configuration file is conveyed in Apexlang and JSON schema below.

Apexlang

namespace "apexlang.config.v1"

"The top level elements of the configuration."
type Configuration {
  "The path to the apex specification file."
  schema: string,
  "Global configuration settings available to all targets (optional)."
  config: {string: any}?,
  "The map of target files to generate and their settings."
  generates: {string: Target}
}

"The configuration for how a target file is generated."
type Target {
  "The TypeScript module containing the visitor class."
  module: string,
  "The name of the exported visitor class that generates the file contents."
  visitorClass: string,
  "When true, the file is only generated if it does not exist. This is useful for scafolded files."
  ifNotExists: bool = false,
  "Target-level configuration (optional)."
  config: {string: any}?
  "Commands to execute that relate to this target (e.g., other code generation tools)."
  runAfter: [Command]?
}

"A command to execute after code generator."
type Command {
  "The command to execute."
  command: string
  "The working directory (optional - default is the current directory)."
  dir: string?
}

JSON schema

{
  "$id": "https://apexlang.io/schemas/configuration.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Apexlang Configuration File Schema",
  "$ref": "#/$defs/Configuration",
  "$defs": {
    "Configuration": {
      "properties": {
        "schema": {
          "description": "The path to the apex specification file.",
          "type": "string"
        },
        "config": {
          "description": "Global configuration settings available to all targets (optional).",
          "type": "object",
          "patternProperties": {
            ".*": {}
          }
        },
        "generates": {
          "description": "The map of target files to generate and their settings.",
          "type": "object",
          "patternProperties": {
            ".*": {
              "$ref": "#/$defs/Target"
            }
          }
        }
      },
      "required": ["schema", "generates"]
    },
    "Target": {
      "properties": {
        "module": {
          "description": "The TypeScript module containing the visitor class.",
          "type": "string"
        },
        "visitorClass": {
          "description": "The name of the exported visitor class that generates the file contents.",
          "type": "string"
        },
        "ifNotExists": {
          "description": "When true, the file is only generated if it does not exist. This is useful for scafolded files.",
          "type": "boolean",
          "default": false
        },
        "config": {
          "description": "Target-level configuration (optional).",
          "type": "object",
          "patternProperties": {
            ".*": {}
          }
        },
        "runAfter": {
          "description": "Commands to execute that relate to this target (e.g., other code generation tools).",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Command"
          }
        }
      },
      "required": ["module", "visitorClass"]
    },
    "Command": {
      "properties": {
        "command": {
          "description": "The command to execute.",
          "type": "string"
        },
        "dir": {
          "description": "The working directory (optional - default is the current directory).",
          "type": "string"
        }
      },
      "required": ["command"]
    }
  }
}

Create your first apex.yaml configuration

A common task with regard to API and microservice development is sharing OpenAPI and gRPC specifications with other teams. In this next step, we will generate the specifications for our URL Shortener service. In the root of your urlshortener directory, create a file named apex.yaml:

apex.yaml

spec: apex.axdl
generates:
  openapi.yaml:
    module: 'https://deno.land/x/apex_codegen@v0.1.9/openapiv3/mod.ts'
    visitorClass: OpenAPIV3Visitor
  proto/service.proto:
    module: 'https://deno.land/x/apex_codegen@v0.1.9/proto/mod.ts'
    visitorClass: ProtoVisitor
    config:
      options:
        go_package: 'github.com/myorg/myapps/pkg/urlshortener'

info

Using config, ifNotExists, and runAfter will be demonstrated later in this tutorial.