Incorrect Response using OpenAPI

[melloware]

Describe the bug
When mapping using OpenApi the HttpProblem definition does not match the binding.

For example:

@Provider
public class BundleRenderValidationExceptionMapper implements ExceptionMapper<BundleRenderValidationException> {
    @Override
    @APIResponse(
            responseCode = "400",
            description = "Validation of bundle failed",
            content = @Content(mediaType = "application/problem+json", schema = @Schema(implementation = HttpProblem.class))
    )
    public Response toResponse(BundleRenderValidationException exception) {
        return exception.getResponse();
    }
}

When reviewing the example document in OpenAPI:

This is incorrect in multiple ways.

1. statusCode is actually status when rendered by Jackson renderer.
2. The headers and parameters get flattened.
3. It does not have desciptions and examples of @Schema open api fields showing a downstream user and documenting it.
4. It generates INCORRECT code for clients generating from OpenAPI like Typescript.

Example flat payload with MDC trace, span, parent.

{
  "status": 404,
  "title": "Not Found",
  "detail": "Logo image not found",
  "instance": "/api/v1/brand/logo",
  "traceId": "185a8b49591673349c3e7f691a1e069b",
  "spanId": "6008077d63144c9b",
  "parentId": "6008077d63144c9b"
}

This won't bind correctly to clients using our OpenAPI Spec.

working with @tmulle we have created one that documents well but we have to hand code any MDC variables like X-Request-Id which is not ideal.

/**
 * Represents an HTTP Problem Response according to RFC 7807. This class
 * encapsulates details about
 * an error that occurred during HTTP request processing.
 */
@Data
@Schema(description = "HTTP Problem Response according to RFC 7807")
public class HttpProblemResponse {

    /** A URI reference that identifies the problem type */
    @Schema(description = "A URI reference that identifies the problem type", example = "https://example.com/errors/validation")
    private URI type;

    /** A short, human-readable summary of the problem type */
    @Schema(description = "A short, human-readable summary of the problem type", example = "Not Found Error")
    private String title;

    /** The HTTP status code for this occurrence of the problem */
    @JsonProperty(value = "status")
    @Schema(description = "The HTTP status code for this occurrence of the problem", example = "400")
    private int statusCode;

    /** A human-readable explanation specific to this occurrence of the problem */
    @Schema(description = "A human-readable explanation specific to this occurrence of the problem", example = "Record not found")
    private String detail;

    /** A URI reference that identifies the specific occurrence of the problem */
    @Schema(description = "A URI reference that identifies the specific occurrence of the problem", example = "https://api.example.com/errors/123")
    private URI instance;

    /** Additional parameters providing more details about the problem */
    @Schema(description = "Additional parameters providing more details about the problem", example = "{\"timestamp\":\"2024-03-20T10:00:00Z\",\"traceId\":\"550e8400-e29b-41d4-a716-446655440000\"}")
    private Map<String, Object> parameters;

    /** HTTP headers associated with the problem response */
    @Schema(description = "HTTP headers associated with the problem response", example = "{\"Content-Type\":\"application/problem+json\",\"X-Request-ID\":\"req-123\"}")
    private Map<String, Object> headers;

    /** List of validation violations that occurred */
    @Schema(description = "List of validation constraint violations that occurred")
    private List<Violation> violations;

    /**
     * Represents a validation violation within the HTTP Problem Response. Contains
     * details about a
     * specific validation error.
     */
    @Data
    @Schema(description = "Validation constraint violation details")
    public static class Violation {
        /** The field that failed validation */
        @Schema(description = "The field that failed validation", example = "email")
        private String field;

        /** Location where the validation error occurred */
        @Schema(description = "Location where the validation error occurred", example = "body")
        private String in;

        /** Description of the validation error */
        @Schema(description = "Description of the validation error", example = "Invalid email format")
        private String message;
    }
}

This generates an OpenAPI with examples and documentation like this...

{
  "type": "https://example.com/errors/validation",
  "title": "Not Found Error",
  "status": 400,
  "detail": "Record not found",
  "instance": "https://api.example.com/errors/123",
  "parameters": {
    "timestamp": "2024-03-20T10:00:00Z",
    "traceId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "headers": {
    "Content-Type": "application/problem+json",
    "X-Request-ID": "req-123"
  },
  "violations": [
    {
      "field": "email",
      "in": "body",
      "message": "Invalid email format"
    }
  ]
}

I am trying to think of a clever way of updating HttpProblem without breaking backwards compatibility but this would be a huge win for anyone using OpenAPI and giving their spec out to customers to generate code.

cc @tmulle cc @turing85 cc @cvgaviao

[tmulle]

I believe this will also fix or enhance this issue also?
#453

[melloware]

as an example of how its wrong when I take my OpenAPI JSON generated above and try and generate some client React TypeScript code this is what gets generated.

export type HttpProblemParameters = { [key: string]: unknown };

export type HttpProblemHeaders = { [key: string]: unknown };

export interface HttpProblem {
	type?: string;
	title?: string;
	statusCode?: number;
	detail?: string;
	instance?: string;
	parameters?: HttpProblemParameters;
	headers?: HttpProblemHeaders;
	/** @deprecated */
	status?: StatusType;
}

export interface StatusType {
	statusCode?: number;
	family?: Family;
	reasonPhrase?: string;
}

So in this case spanId, traceId etc would be lost and never appear in this decoded JSON on the client side.

[tmulle]

That is what happens as well when I use the quarkus-openapi-generator to generate the Java code as well.
It generates the StatusType object which then causes an error when trying to build the Pojo because it is looking for a constructor that takes just the status number.

I also tried telling the openapi generator to ignore 'deprecated' fields since you have the StatusType marked as such but then Jackson doesn't fill in the status code when deserializing.

[melloware]

I published this new lib you can read about the differences.

<dependency>
    <groupId>com.melloware.openapi-problem</groupId>
    <artifactId>quarkus-openapi-problem</artifactId>
    <version>0.0.1</version>
</dependency>

But it solves this problem and now generates this elegant TypeScript that matches the backend.

/**
 * Additional parameters providing more details about the problem
 */
export type HttpProblemContext = { [key: string]: unknown };

/**
 * HTTP Problem Response according to RFC 9457
 */
export interface HttpProblem {
    /** A URI reference that identifies the problem type */
    type?: string;
    /** A short, human-readable summary of the problem type */
    title?: string;
    /** The HTTP status code for this occurrence of the problem */
    status?: number;
    /** A human-readable explanation specific to this occurrence of the problem */
    detail?: string;
    /** A URI reference that identifies the specific occurrence of the problem */
    instance?: string;
    /** Additional parameters providing more details about the problem */
    context?: HttpProblemContext;
    /** List of validation constraint violations that occurred */
    errors?: Violation[];
    /** Original cause of error, only set when forwarding an underlying problem */
    cause?: HttpProblem;
}

/**
 * Validation constraint violation details
 */
export interface Violation {
    /** The field that failed validation */
    pointer?: string;
    /** Location where the validation error occurred such as query, path, header, form, body */
    in?: string;
    /** Description of the validation error */
    detail?: string;
}