How can I document an Enum value?

[cristalp]

According to https://swagger.io/docs/specification/v3_0/data-models/enums/ it's possible to add a description to Enum values.

However, annotating them in my code with @Schema(description = "...") doesn't do anything.

Is this supported in Smallrye?

[MikeEdgar]

I think the description is applied at the parameter level in the example. You can put Markdown in the description so it appears more readable. That's what is shown in the linked doc (in-lined below).

parameters:
  - in: query
    name: sort
    schema:
      type: string
      enum: [asc, desc]
    description: >
      Sort order:
       * `asc` - Ascending, from A to Z
       * `desc` - Descending, from Z to A

[cristalp]

Thanks! But then it's not possible to do that in the Enum itself?

[MikeEdgar]

You mean on the individual enum entries? You should be able to place the @Schema on the enum (class-level) itself, although in that case it won't apply to a parameter, but be contained in the schema.

[cristalp]

I'm not sure whether we're talking about the same thing.

I should have written an example from the beginning, but better late than never :-)

That's what I mean:

@Schema(description = "The Foo")
public enum Foo {

  @Schema(description = "The Bar")
  BAR,

  @Schema(description = "The Baz")
  BAZ;
}

[MikeEdgar]

Yeah, that's what I was thinking too. The way schema is structured, you need to place the description for all of the entries (BAR, BAZ, etc) into the description on Foo.

[cristalp]

Ok, thanks for the information!