OpenAPITools / OpenAPITools/openapi-generator

[BUG][C#] Should use nullable types for non-required properties

Open
#4,816 11 comments 20 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Client: C-Sharp Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Bug Report Checklist
  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator (example)?
  • What's the version of OpenAPI Generator used?
  • Have you search for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Bounty to sponsor the fix (example)
Description

The C# generators currently generate model classes using non-nullable types for properties which are not required, which can't represent instances where those properties are not present.

openapi-generator version

v4.0.0 and later

OpenAPI declaration file content or url
Example OpenAPI 3.0.2 document
openapi: '3.0.2'
info:
  title: non-required property example
  version: '1.0.0'
components:
  schemas:
    DateRange:
      description: A possibly open-ended date range.
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
      required:
      - start
paths:
  /date-ranges:
    get:
      operationId: getDateRanges
      responses:
        default:
          description: Get date ranges
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DateRange'
    post:
      operationId: addDateRange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DateRange'
      responses:
        '201':
          description: Success

Note that end is not declared nullable: true because end is never null in the JSON produced or consumed by the API. It is either a date string, or not present.

Command line used for generation

java -jar openapi-generator-cli.jar generate -g csharp-netcore -i openapi.yaml -o generated

Steps to reproduce
  1. Ensure the API returns at least one open-ended range (i.e. a DateRange object without an end property).
  2. Call GetDateRanges and note that End for the open-ended range is DateTime(1900-01-01), which is problematic since it is indistinguishable from "end":"1900-01-01" and likely violates the constraint that End is not before Start.
  3. Note that there is no way to call AddDateRange with an open-ended range, since End will always have a value.
Related issues/PRs

The regression occurred between v3.0.2 and v4.0.0. Bisect says the first bad commit is 3744273312 (v4.0.0), so I'm obviously doing something wrong. (Maybe cli is using published core of same version, rather than locally-built version?) Advice on how to bisect would be appreciated.

The issue was also discussed in https://github.com/OpenAPITools/openapi-generator/issues/3725#issuecomment-545039145.

Suggest a fix

I believe nullable types should be used for properties which are either nullable or not required, since null in C# is a reasonable representation of both JSON properties which are null and properties which are not present.

Thanks for considering,
Kevin

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the example from the issue using openapi.yaml and the csharp-netcore command, comparing the generated DateRange model with the v3.0.2 and v4.0.0 behavior. Then trace the C# generator's handling of required and non-required properties and identify the relevant regression coverage. Done means open-ended DateRange values can be represented without conflating absence with a concrete date, with tests covering the reported case.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, java, openapi
Domain
api, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.