[FEATURE] Better support for optional/nullable enums

[zbarbuto]

tl;dr:

ExampleResponse.fromJson(<String, dynamic>{'status': null}) != ExampleResponse(status: null);

Is your feature request related to a problem? Please describe.

Enum values always fallback to enums.$name.swaggerGeneratedUnknown; even if the value is nullable or has a default value of null.

For example, take the following spec:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Get Example
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExampleResponse'
components:
  schemas:
    ExampleResponse:
      type: object
      properties:
        status:
          type: string
          default: null
          enum:
            - active
            - inactive
            - null
          nullable: true

This is fine in most instances swaggerGeneratedUnknown is fine since it serialises to null, but since the value itself is nullable, it means that two entities that should be equal at runtime, aren't. This tends to come up in tests a bit.

e.g. if I run:

import 'foo.swagger.dart';

void main() {
  print(ExampleResponse.fromJson(<String, dynamic>{}) == ExampleResponse());
  print(ExampleResponse.fromJson(<String, dynamic>{'status': null}) ==
      ExampleResponse());
  // even using the enum value generated by this library which is `$null`
  print(ExampleResponse.fromJson(<String, dynamic>{'status': null}) ==
      ExampleResponse(status: ExampleResponseStatus.$null));
}

I get false false false since the actual value is ExampleResponse(status: ExampleResponseStatus.swaggerGeneratedUnknown)

Describe the solution you'd like

Ideally, null values on optional enums are treated as first-class null instead of an enum value that has a json value of null.
At the very least I would expect that:

ExampleResponse.fromJson(<String, dynamic>{'status': null}) == ExampleResponse(status: null);

For this to work, I think that the generated exampleResponseStatusFromJson needs to avoid returning swaggerGeneratedUnknown and instead have that value in the @JsonKey decorator on the property itself:

Something like:

enums.ExampleResponseStatus? exampleResponseStatusFromJson(Object? exampleResponseStatus) {
  return enums.ExampleResponseStatus.values
          .firstWhereOrNull((e) => e.value == exampleResponseStatus;
}

class ExampleResponse {
  // ...
  @JsonKey(
    name: 'status',
    toJson: exampleResponseStatusToJson,
    fromJson: exampleResponseStatusFromJson,
    defaultValue: null // or whatever `defaultValue` is, falling back to `swaggerGeneratedUnknown` if there isn't one
  )
  final enums.ExampleResponseStatus? status;