How do I generate OpenAPI to upload two binary files? It worked with Swagger annotations.

[cristalp]

We have a class Binary, which is a wrapper around a byte array. This is often used within an object to upload files to a REST endpoint.

With Swagger annotations, the object looked like this:

@Schema(description = "Data for comparing two PDF documents")
public class PdfComparisonFiles {

  @Schema(description = "The expected PDF document", format = "binary", type = "string")
  @NotNull
  private Binary expected;

  @Schema(description = "The actual PDF document", format = "binary", type = "string")
  @NotNull
  private Binary actual;

...
}

This resulted in the following part of openapi.json:

      "PdfComparisonFiles" : {
        "required" : [ "actual", "expected" ],
        "type" : "object",
        "properties" : {
          "actual" : {
            "type" : "string",
            "description" : "The actual PDF document",
            "format" : "binary"
          },
          "expected" : {
            "type" : "string",
            "description" : "The expected PDF document",
            "format" : "binary"
          }
        },
        "description" : "Data for comparing two PDF documents"
      }

And in SwaggerUI, I get two buttons for uploading the files.

Trying the same with the Eclipse MicroProfile annotations:

@Schema(description = "Data for comparing two PDF documents")
public class PdfComparisonFiles {

  @Schema(description = "The expected PDF document", format = "binary", type = SchemaType.STRING)
  @NotNull
  private Binary expected;

  @Schema(description = "The actual PDF document", format = "binary", type = SchemaType.STRING)
  @NotNull
  private Binary actual;

...
}

But here I first get an error message in SwaggerUI:

Resolver error at paths./api/pdf/simple-compare.post.requestBody.content.multipart/form-data.schema.properties.expected.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/Binary does not exist in document

And the result in openapi.json is also different (and doesn't work in SwaggerUI):

      "PdfComparisonFiles" : {
        "description" : "Data for comparing two PDF documents",
        "required" : [ "expected", "actual" ],
        "type" : "object",
        "properties" : {
          "expected" : {
            "format" : "binary",
            "description" : "The expected PDF document",
            "type" : "object",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Binary"
            } ]
          },
          "actual" : {
            "format" : "binary",
            "description" : "The actual PDF document",
            "type" : "object",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Binary"
            } ]
          }
        }
      }

So my question is: What do I have to annotate to get the same result as with Swagger annotations? Thanks for any help!

[MikeEdgar]

@cristalp , try placing @Schema(format = "binary", type = "string") directly on the Binary class. If that doesn't work try @Schema(format = "binary", type = "string", implementation = String.class). You can then simplify the instances/fields using Binary and remove format and type from the @Schema annotations there.

[cristalp]

Wow, faster than a lightning! :-)

Thanks for your response! I tried both approaches that you suggested, the second being:

@Schema(format = "binary", type = SchemaType.STRING, implementation = String.class)
public interface Binary {
...
}

and

@Schema(description = "Data for comparing two PDF documents")
public class PdfComparisonFiles {

  @Schema(description = "The expected PDF document")
  @NotNull
  private Binary expected;

  @Schema(description = "The actual PDF document")
  @NotNull
  private Binary actual;

...
}

But in both cases, the generated OpenAPI was inconsistent (a bug perhaps?). One of the both was correct, though.

      "PdfComparisonFiles" : {
        "description" : "Data for comparing two PDF documents",
        "required" : [ "expected", "actual" ],
        "type" : "object",
        "properties" : {
          "expected" : {
            "description" : "The expected PDF document",
            "type" : "object",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Binary"
            } ]
          },
          "actual" : {
            "description" : "The actual PDF document",
            "type" : "string",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Binary"
            } ]
          }
        }
      }

actual is shown correctly with the upload button in SwaggerUI.

[MikeEdgar]

Progress :) For the second approach (@Schema(format = "binary", type = SchemaType.STRING, implementation = String.class)) did both expected and actual display properly? In your example where expected has type: object is that just demonstrating the first @Schema suggestion with implementation?

[cristalp]

No, with or without implementation, the result was always that actual displayed properly, but expected didn't. Note: In reality, it's documented in German...

[MikeEdgar]

You can add implementation = String.class also to expected, but it's definitely strange they don't both get the same schema since the only difference between them is the description and the field name. Are there any other differences that aren't shown in the examples?

[cristalp]

Well, I added implementation = String.class to both fields, so it doesn't look weird ;-)

Now however, it just generates

      "PdfComparisonFiles" : {
        "description" : "Die Daten für den Vergleich zweier PDF-Dokumente",
        "required" : [ "expected", "actual" ],
        "type" : "object",
        "properties" : {
          "expected" : {
            "description" : "Das erwartete PDF-Dokument",
            "type" : "string"
          },
          "actual" : {
            "description" : "Das tatsächliche PDF-Dokument",
            "type" : "string"
          }
        }
      }

And SwaggerUI just shows two text fields.

I don't quite understand what you mean with "any other differences". In the end, the openapi.json has to be generated correctly, and SwaggerUI reacts to that.

But going all the way and adding everything to both fields (i.e. format = "binary", type = SchemaType.STRING, implementation = String.class) seems to do the trick:

      "PdfComparisonFiles" : {
        "description" : "Die Daten für den Vergleich zweier PDF-Dokumente",
        "required" : [ "expected", "actual" ],
        "type" : "object",
        "properties" : {
          "expected" : {
            "format" : "binary",
            "description" : "Das erwartete PDF-Dokument",
            "type" : "string"
          },
          "actual" : {
            "format" : "binary",
            "description" : "Das tatsächliche PDF-Dokument",
            "type" : "string"
          }
        }
      }

[MikeEdgar]

Ok, it makes sense that works. The part I don't quite understand is how one of the fields was type: object but the other was type: string when their types and annotations were basically the same.

[cristalp]

I don't understand it either.

Now, just to be sure, I removed the annotation from Binary and also added another field to check:

@Schema(description = "Die Daten für den Vergleich zweier PDF-Dokumente")
public class PdfComparisonFiles {

  @Schema(description = "Das erwartete PDF-Dokument", format = "binary", type = SchemaType.STRING, implementation = String.class)
  @NotNull
  private Binary expected;

  @Schema(description = "Das tatsächliche PDF-Dokument", format = "binary", type = SchemaType.STRING, implementation = String.class)
  @NotNull
  private Binary actual;

  @Schema(description = "Foo", format = "binary", type = SchemaType.STRING, implementation = String.class)
  @NotNull
  private ByteBuffer foo;
...
}

And sure enough:

      "PdfComparisonFiles" : {
        "description" : "Die Daten für den Vergleich zweier PDF-Dokumente",
        "required" : [ "expected", "actual", "foo" ],
        "type" : "object",
        "properties" : {
          "expected" : {
            "format" : "binary",
            "description" : "Das erwartete PDF-Dokument",
            "type" : "string"
          },
          "actual" : {
            "format" : "binary",
            "description" : "Das tatsächliche PDF-Dokument",
            "type" : "string"
          },
          "foo" : {
            "format" : "binary",
            "description" : "Foo",
            "type" : "string"
          }
        }
      }

Perhaps it was just some weird dependency problem on my part... you never know with Maven ;-)

To sum up, this is what's required, correct?

@Schema(description = "...", format = "binary", type = SchemaType.STRING, implementation = String.class)

[MikeEdgar]

To sum up, this is what's required, correct?

@Schema(description = "...", format = "binary", type = SchemaType.STRING, implementation = String.class)

That's correct. If you want to simply it further, the type is superfluous when the implementation is String

@Schema(description = "...", format = "binary", implementation = String.class)

[cristalp]

Great! Thanks a lot, Mike!