oapi-codegen-dd

Using the x-go-type (and optionally, x-go-type-import when you need to import another package) allows overriding the type that oapi-codegen determined the generated type should be.

We can see this at play with the following schemas:

components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          # this is a bit of a contrived example, as you could instead use
          # `format: uuid` but it explains how you'd do this when there may be
          # a clash, for instance if you already had a `uuid` package that was
          # being imported, or ...
          x-go-type: googleuuid.UUID
          x-go-type-import:
            path: github.com/google/uuid
            name: googleuuid
        id:
          type: number
          # ... this is also a bit of a contrived example, as you could use
          # `type: integer` but in the case that you know better than what
          # oapi-codegen is generating, like so:
          x-go-type: int64

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	Id   *int64          `json:"id,omitempty"`
	Name googleuuid.UUID `json:"name"`
}

You can see this in more detail in the example code.

By default, oapi-codegen will generate a pointer for optional fields.

Using the x-go-type-skip-optional-pointer extension allows omitting that pointer.

We can see this at play with the following schemas:

components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
          x-go-type-skip-optional-pointer: true

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	Id   float32 `json:"id,omitempty"`
	Name string  `json:"name"`
}

You can see this in more detail in the example code.

By default, oapi-codegen will attempt to generate the name of fields and types in as best a way it can.

However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with x-go-name.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-go-name
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      # can be used on a type
      x-go-name: ClientRenamedByExtension
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
          # or on a field
          x-go-name: AccountIdentifier

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientRenamedByExtension defines model for ClientWithExtension.
type ClientRenamedByExtension struct {
	AccountIdentifier *float32 `json:"id,omitempty"`
	Name              string   `json:"name"`
}

You can see this in more detail in the example code.

[!NOTE] Notice that this is subtly different to the x-go-name, which also applies to fields within structs.

By default, oapi-codegen will attempt to generate the name of types in as best a way it can.

However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with x-go-name.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-go-type-name
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      x-go-type-name: ClientRenamedByExtension
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
          # NOTE attempting a `x-go-type-name` here is a no-op, as we're not producing a _type_ only a _field_
          x-go-type-name: ThisWillNotBeUsed

From here, we now get two different models and a type alias:

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension = ClientRenamedByExtension

// ClientRenamedByExtension defines model for .
type ClientRenamedByExtension struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

You can see this in more detail in the example code.

In a case that you may want to add the JSON struct tag omitempty to types that don't have one generated by default - for instance a required field - you can use the x-omitempty extension.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-omitempty
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          # for some reason, you may want this behavior, even though it's a required field
          x-omitempty: true
        id:
          type: number

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name,omitempty"`
}

You can see this in more detail in the example code.

By default, oapi-codegen will generate json:"..." struct tags for all fields in a struct, so JSON (un)marshaling works.

However, sometimes, you want to omit fields, which can be done with the x-go-json-ignore extension.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-go-json-ignore
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        complexField:
          type: object
          properties:
            name:
              type: string
            accountName:
              type: string
          # ...
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        complexField:
          type: object
          properties:
            name:
              type: string
            accountName:
              type: string
          # ...
          x-go-json-ignore: true

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	ComplexField *struct {
		AccountName *string `json:"accountName,omitempty"`
		Name        *string `json:"name,omitempty"`
	} `json:"complexField,omitempty"`
	Name string `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	ComplexField *struct {
		AccountName *string `json:"accountName,omitempty"`
		Name        *string `json:"name,omitempty"`
	} `json:"-"`
	Name string `json:"name"`
}

Notice that the ComplexField is still generated in full, but the type will then be ignored with JSON marshalling.

You can see this in more detail in the example code.

If you're making use of a field's struct tags to i.e. apply validation, decide whether something should be logged, etc, you can use x-oapi-codegen-extra-tags to set additional tags for your generated types.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-oapi-codegen-extra-tags
components:
  schemas:
    Client:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
        id:
          type: number
          x-oapi-codegen-extra-tags:
            validate: "required,min=1,max=256"
            safe-to-log: "true"
            gorm: primarykey

From here, we now get two different models:

// Client defines model for Client.
type Client struct {
	Id   float32 `json:"id"`
	Name string  `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	Id   float32 `gorm:"primarykey" json:"id" safe-to-log:"true" validate:"required,min=1,max=256"`
	Name string  `json:"name"`
}

You can see this in more detail in the example code.

The x-sensitive-data extension allows you to mark fields as containing sensitive information that should be automatically masked when marshaling to JSON. This is useful for preventing accidental logging or exposure of sensitive data like passwords, API keys, credit card numbers, etc.

The extension supports several masking strategies:

• full: Replace the entire value with a fixed-length mask ("********") to hide both content and length
• regex: Mask only parts of the value matching a regex pattern (keeps context visible)
• hash: Replace the value with a SHA256 hash (one-way, useful for verification)
• partial: Mask the middle part while keeping prefix/suffix visible (e.g., show last 4 digits of credit card)

Example:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Sensitive Data Example
components:
  schemas:
    User:
      type: object
      properties:
        email:
          type: string
          x-sensitive-data:
            mask: full
        ssn:
          type: string
          x-sensitive-data:
            mask: regex
            pattern: '\d{3}-\d{2}-\d{4}'
        creditCard:
          type: string
          x-sensitive-data:
            mask: partial
            keepSuffix: 4  # Show last 4 digits
        apiKey:
          type: string
          x-sensitive-data:
            mask: hash
            algorithm: sha256

This generates:

type User struct {
    Email      *string `json:"email,omitempty" sensitive:""`
    Ssn        *string `json:"ssn,omitempty" sensitive:""`
    CreditCard *string `json:"creditCard,omitempty" sensitive:""`
    ApiKey     *string `json:"apiKey,omitempty" sensitive:""`
}

func (u User) MarshalJSON() ([]byte, error) {
    // Custom marshaler that masks sensitive fields
    // ...
}

When marshaling to JSON:

• email: "user@example.com" becomes email: "********" (fixed length, hides original length)
• ssn: "123-45-6789" becomes ssn: "***-**-****" (digits masked, structure visible)
• creditCard: "1234-5678-9012-3456" becomes creditCard: "********3456" (last 4 visible)
• apiKey: "my-secret-key" becomes apiKey: "325ededd6c3b9988f623c7f964abb9b016b76b0f8b3474df0f7d7c23b941381f" (SHA256 hash)

Partial masking options:

• keepPrefix: Number of characters to keep at the start
• keepSuffix: Number of characters to keep at the end

You can see this in more detail in the example code.

When consuming an enum value from an external system, the name may not produce a nice variable name. Using the x-enum-names extension allows overriding the name of the generated variable names.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-enum-names
components:
  schemas:
    ClientType:
      type: string
      enum:
        - ACT
        - EXP
    ClientTypeWithNamesExtension:
      type: string
      enum:
        - ACT
        - EXP
      x-enum-names:
        - Active
        - Expired

From here, we now get two different forms of the same enum definition.

// Defines values for ClientType.
const (
	ACT ClientType = "ACT"
	EXP ClientType = "EXP"
)

// ClientType defines model for ClientType.
type ClientType string

// Defines values for ClientTypeWithExtension.
const (
	Active  ClientTypeWithExtension = "ACT"
	Expired ClientTypeWithExtension = "EXP"
)

// ClientTypeWithExtension defines model for ClientTypeWithExtension.
type ClientTypeWithExtension string

You can see this in more detail in the example code.

When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using x-deprecated-reason.

We can see this at play with the following schemas:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-deprecated-reason
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          deprecated: true
          x-deprecated-reason: Don't use because reasons
        id:
          type: number
          # NOTE that this doesn't generate, as no `deprecated: true` is set
          x-deprecated-reason: NOTE you shouldn't see this, as you've not deprecated this field

From here, we now get two different forms of the same enum definition.

// Client defines model for Client.
type Client struct {
	Id   *float32 `json:"id,omitempty"`
	Name string   `json:"name"`
}

// ClientWithExtension defines model for ClientWithExtension.
type ClientWithExtension struct {
	Id *float32 `json:"id,omitempty"`
	// Deprecated: Don't use because reasons
	Name string `json:"name"`
}

Notice that because we've not set deprecated: true to the name field, it doesn't generate a deprecation warning.

You can see this in more detail in the example code.