search

OpenLiberty / open-liberty

Open Liberty is a highly composable, fast to start, dynamic application server runtime environment
https://openliberty.io
Eclipse Public License 2.0
1.15k stars 587 forks source link

mpOpenAPI produces incomplete docs and prints false error messages #13176

Open bmarwell opened 4 years ago

bmarwell commented 4 years ago

This is just a bug report which was created by request from one of your team members, as my findings turned out to be a bug.

Describe the bug See https://github.com/OpenLiberty/open-liberty/issues/12936#issuecomment-657556194

Steps to Reproduce See https://github.com/OpenLiberty/open-liberty/issues/12936#issuecomment-657556194

Expected behavior See https://github.com/OpenLiberty/open-liberty/issues/12936#issuecomment-657556194

Diagnostic information:

Additional context None.

msmiths commented 4 years ago

@arturdzm @leochr @arthurdm

Azquelt commented 2 years ago

Summarizing the bug from #12963:

@APIResponse(
          responseCode = "201",
          description = "task created successfully",
          headers = {@Header(
              name = "task-id",
              description = "ID of the created task.",
              required = true,
              allowEmptyValue = false,
              schema = @Schema(implementation = TaskId.class)
          )}
      )
@POST
@Path("/")
public Response postTask(TaskContents body);

produces this on mpOpenApi-1.1:

      responses:
        201:
          description: task created successfully
          headers:
            bars-id:
              description: ID of the created bar.
              required: true
              style: simple

and produces this on mpOpenApi-2.0:

      responses:
        201:
          description: task created successfully
          headers:
            bars-id:
              description: ID of the created bar.
              required: true
              allowEmptyValue: false
              style: simple
              schema:
                $ref: '#/components/schemas/UUID'

In mpOpenApi-1.1, the schema = @Schema(implementation = TaskId.class) appears to be ignored, resulting in no schema being listed for the header (and therefore a validation failure of the OpenAPI document).

Note that the missing allowEmptyValue: false is not a bug as false is the default value for this key, so omitting it is allowed.

In mpOpenApi-2.0, the bug is not present, the schema section is generated correctly.