Macro Help

[Vince-Smith]

I'm struggling to understand the intended use of macros and was hoping someone could point me in the right direction.

A place these seemed useful to me was to dynamically override years in my defaults/examples.

Unfortunately, I'm finding that neither modelPropertyMacro nor parameterMacro seem very well suited for this despite them being documented as having that purpose...

For example you can't introspect the path you're in, so if you want to modify a parameter you can only do so by it's name which effects everything in the entire document. Even though an operation is passed in to parameterMacro, if there's conditional logic tied to the key that produced that object then it's useless.

modelPropertyMacro has similar problems in that you are given the property but not the name of the property, making it impossible to implement conditional dynamic examples.

And finally I can't for the life of me figure out what the default return value is supposed to be...

// This configuration blows up entirely
'parameterMacro': function (operation, parameter) {
    if (parameter.name === 'year') {
        return 2025
    }
}

// This one sets the default of every non-year property to null
'parameterMacro': function (operation, parameter) {
    if (parameter.name === 'year') {
        return 2025
    }
    return null
}

// This one sets the default of every non-year property to the resolved parameter _object_
'parameterMacro': function (operation, parameter) {
    if (parameter.name === 'year') {
        return 2025
    }
    return parameter
}

It seems like I should be doing something like return parameter.default ?? parameter.value as my fallback but I can't tell if that's the intent.

Am I using these macro's completely wrong??

[saky-semicolon]

You're on the right track — macros in Swagger/OpenAPI (like parameterMacro and modelPropertyMacro) are mainly for overriding or generating default values dynamically.

• Default return value → You should return the original property value if you don’t want to override it.
• For parameters, that’s usually parameter.default (or parameter itself depending on context).
• For properties, it’s the same idea — return the incoming property unchanged unless you want to modify it.

Example:

'parameterMacro': function (operation, parameter) {
  if (parameter.name === 'year') {
    return 2025
  }
  return parameter.default // fallback to original
}

[Vince-Smith]

Interesting... 🤔 I appreciate the feedback!

I feel like maybe I have my wires cross about what "default" is supposed to be used for then.

Because per the docs:

Use the default keyword in the parameter schema to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request.

So from this I'd infer that parameterMacro should only really be used to represent a server-side default that changes dynamically... like from an env var or time based threshold (which arguably I guess should just be dynamically added to the spec file itself so consumers that aren't using the UI will see it too).

It feels to me like the intent of parameterMacro is more about overriding the placeholder value that folks see when using the ui to execute requests, not so much modifying the specs actual default.

I'm wondering if the terms default and placeholder are being used interchangeably on the ui side of things and maybe that doesn't 100% align the intent of what an OpenAPI's interpretation of default is?