Open API Spec V2.0 - Default value of a field of type Enum

Question

I have a request body for an API specification in Swagger V2.0, which looks like follows.

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      $ref: '#/definitions/StatusEnum'

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']

Now, I want StatusObject.status to have the value UNKNOWN by default, if it is not set from the client end. I tried to achieve this as follows, with no luck.

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      $ref: '#/definitions/StatusEnum'
      default: 'UNKNOWN'

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']

I also have tried with '#/definitions/StatusEnum.UNKNOWN' which again didn't work. Combed through the documentation as well but couldn't find anything further. What am I missing?

Response to marked duplicate

What I am trying to achieve is to set a default value for this property status. This works when the enum is defined in line as follows.

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      type: string
      enum:
        - 'ALPHA'
        - 'BRAVO'
        - 'UNKNOWN'
      default: 'UNKNOWN'

But, this won't work for me, as I'd like to reuse the enum, which otherwise I'll have to repeat at multiple places.

Viglione

You need to wrap the $ref into allOf, as explained here. – Arteriosclerosis

Thanks... I will leave this question on for reference purposes. – Viglione

@Helen, I doubt if wrapping $ref in allOf works. Because I am still unable to enforce the default constraint. The default value of status of generated POJO is still null... – Viglione

Could be an issue with the openapi-generator. – Arteriosclerosis

Yeah. Could be... – Viglione

Answer 1

Since this is just a workaround and I am not sure if I can confirm if this is an answer, I won't mark this as accepted answer. That way, I think it will be still open for someone who figured out the right way, or a better way to achieve the expectation.

Apparently, the problem is with $ref. It's already known that the siblings of $ref are ignored in OpenAPI V2.0. So, enforcing any further constraints once you use $ref won't be possible.

For my specific use case, since I want to reuse my enum definition, I used YAML Anchors as defined in V2.0 docs. Even though the enum definition is repeated in each POJO it's not that much of a headache to manage, at least for the time being. The implementation I came up is as follows.

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      enum: *STATUS_ENUM # Referencing the anchor
      default: 'UNKNOWN'

  StatusEnum:
    type: string
    enum: &STATUS_ENUM # This is the anchor
      - 'ALPHA'
      - 'BRAVO'
      - 'UNKNOWN'

It must also be noted that, the enum values in this case cannot be defined using array syntax (i.e. ['ALPHA', 'BRAVO', 'UNKNOWN']) as it'll break the YAML syntax rules when you try to use YAML anchors alongside that.

Viglione

Answer 2

OpenAPI 3.1 supports default alongside $ref, e.g.

  status:
    $ref: '#/definitions/StatusEnum'
    default: 'UNKNOWN'

With OpenAPI 3.0, you can use allOf, e.g.

  status:
    allOf:
      - $ref: '#/definitions/StatusEnum'
      - default: 'UNKNOWN'

Harriet