Special fields #

The AsyncAPI specification allows to define any custom fields prefixed with x-. Any tool that processes the AsyncAPI document may use and interpret these fields in any way. This feature is called extensions.

These fields may be placed in many places in the document with any value. Specifically, the go-asyncapi tool reads only the special fields described below, and ignores others.

This article describes the special fields that are used by the go-asyncapi tool to customize the generated code on the document level.

x-go-type #

Applies to: Schema, JSONSchema object

This field allows to force the use of a user-defined Go type in the generated code instead of the autogenerated one. For that, go-asyncapi does not generate a type declaration and replaces all its usages (with some exceptions, see below) to the user-defined type. Optionally, it may add imports automatically.

x-go-type may be written in simple and extended forms.

Simple form #

In the simple form, x-go-type is a string with the name of the Go type to replace in all usages. Does not add any extra imports.

Example

components:
  schemas:
    MySchema:
      x-go-type: MyOwnType
      type: object
      properties:
        myField:
          type: string

Extended form #

In the extended form, x-go-type is an object, that allows to specify more details about the type to replace. Possible fields are:

type – the type name. Required. Same meaning as in the simple form.
import – type import settings
- package – optional package name or module to import a type from. E.g. “github.com/your/module” or “time”
embedded – if true, the tool will embed a type in the generated type instead of replacing it. Optional. Default is false.
hint – various hints how this type should be used in the generated Go code. Optional. Possible fields are:
- pointer – true forces the objects of this type to be used as pointers in the generated code. By default, this depends on the context.
- kind – if not empty, overrides the object kind, which slightly changes the way how the type is used in the generated code.

hint.kind supports only "interface" for now, which forces to treat the type as Go interface. For example, for the interface we can’t construct a pointer type in the generated code (e.g. var foo &MyOwnType). Takes the precedence over the pointer hint.

Example

components:
  schemas:
    MySchema:
      x-go-type:
        type: MyOwnType
        import: 
          package: github.com/myorg/mylib
        hint:
          pointer: true
      type: object
      properties:
        myField:
          type: string

x-nullable #

Applies to: Schema, JSONSchema object

x-nullable forcibly marks a field or whole schema as nullable. By default, the field is nullable if it can be null or needed to be checked for nil in the generated code, i.e., marked as required. Nullable fields are generated as pointers in Go code.

Example

components:
  schemas:
    MySchema:
      type: object
      properties:
        myField:
          x-nullable: true
          type: string

x-ignore #

Applies to: Channel, Operation, Message, Schema, Server, Correlation ID, JSONSchema object

If x-ignore field is set to true, the entity is ignored by the go-asyncapi tool. All references to this entity in the generated Go code are automatically replaced with generic types such as any.

Example

channels:
  myChannel:
    x-ignore: true
    messages:
      myMessage:
        payload:
          type: string

x-go-name #

Applies to: Channel, Message, Schema, Server, Parameter, JSONSchema object

This field allows to explicitly set the name of the type in the generated Go code. It overrides any other name, taken from document or generated automatically.

x-go-name may have no effect in some cases, for example, if the jsonschema object is inline type (has not a separate type definition, therefore is not referenced by name).

Example

channels:
  myChannel:
    messages:
      myMessage:
        x-go-name: MyCustomMessageName
        payload:
          type: string

x-go-tags and x-go-tags-values #

Applies to: Schema, JSONSchema object

These fields allow to control the field tags in the generated Go struct. By default, the tags are generated based on the AsyncAPI document content types.

x-go-tags #

x-go-tags can be set in two forms: as a tags list or tags with values list.

If the value is a list of tag names, they’re added to the struct field with values copied from other tags.

If the value is a key-value mapping, the tags are added with the specified values. If such tag already exists, it is replaced with the new value.

Example

Definition

```yaml components: schemas: myModel: type: object properties: id: x-go-tags: - spam - eggs type: integer name: type: string x-go-tags: foo: bar json: baz count: type: integer ```

Produced code

```go package models type MyModel struct { ID int `json:"id" spam:"id" eggs:"id"` Name string `json:"baz" foo:"bar"` Count int `json:"count"` } ```

x-go-tags-values #

x-go-tags-values is a list of values, that are added to every tag in the generated Go struct field.

Example

Definition

```yaml components: schemas: myModel: type: object properties: id: x-go-tags-values: - omitempty x-go-tags: - spam - eggs type: integer name: type: string ```

Produced code

```go package models type MyModel struct { ID int `json:"id,omitempty" spam:"id,omitempty" eggs:"id,omitempty"` Name string `json:"name"` } ```