bug(gen): convenient errors should ignore examples during comparison

[tdakkota]

Discussed in #1372

^{Originally posted by mcclurec December 19, 2024}
The compareResponses method effectively does a deep equal check by marshaling the JSON and comparing their byte array. This means that if you've defined a schema with a standard error type, but provide relevant example errors for different endpoints, ogen doesn't generate a convenient error handler.

I seems like you could safely drop the example and examples properties off the content before doing the comparison. (Relevant OpenAPI schema spec for Media Type Object)

Bonus Points

If the comparison did an equality check to see that the $ref'd object was of the same shape as the manually defined response, you could mix default responses and ones with specific examples.

Example OpenAPI 3.1 schema

The following spec only defines a single error type, and all the default responses are technically equal, but the comparison checker deems them different by doing a deep equality check.

openapi: 3.1.1
info:
  title: Relevent Example Errors

paths:
  /endpoint1:
    get:
      responses:
        200:
          $ref: "#/components/responses/Endpoint1Response"
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      requestBody:
        $ref: '#/components/requestBodies/Endpoint1PatchRequest'
      responses:
        200:
          $ref: "#/components/responses/Endpoint1Response"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                ErrorOutOfRange:
                  $ref: '#/components/examples/ErrorOutOfRange'
                ErrorValueType:
                  $ref: '#/components/examples/ErrorValueType'

  /endpoint2:
    get:
      responses:
        200:
          $ref: "#/components/responses/Endpoint2Response"
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      requestBody:
       $ref: '#/components/requestBodies/Endpoint2PatchRequest'
      responses:
        200:
          $ref: "#/components/responses/Endpoint2Response"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                ErrorIpValidation:
                  $ref: '#/components/examples/ErrorIpAddress'

components:
  schemas:
    Endpoint1:
      type: object
      properties:
        some_integer:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        some_double:
          type: number
          format: double
    Endpoint2:
      type: object
      properties:
        some_string:
          type: string
        some_ip_address:
          type: string
          format: ipv4
          examples: [192.168.0.255]
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          examples: [unique_error_code_string]
        message:
          type: string
          examples: [a helpful human readable description]

  examples:
    ErrorOutOfRange:
      summary: Value out of range
      value:
        code: value_out_of_range
        message: <field> out of range [0, 100]
    ErrorValueType:
      summary: Value must be of proper type
      value:
        code: value_type
        message: <field> must be a <type>
    ErrorIpAddress:
      summary: Value must be a valid IPv4 address
      value:
        code: value_type
        message: some_ip_address must be a valid ipv4 format

  responses:
    Endpoint1Response:
      description: success
      headers:
        'Accept-Patch':
          $ref: "#/components/headers/AcceptPatch"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Endpoint1"
    Endpoint2Response:
      description: success
      headers:
        'Accept-Patch':
          $ref: "#/components/headers/AcceptPatch"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Endpoint2"
    ErrorResponse:
      description: error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

  requestBodies:
    Endpoint1PatchRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Endpoint1'
    Endpoint2PatchRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Endpoint2'

  headers:
    AcceptPatch:
      schema:
        type: string
        enum:
          - application/json
```</div>