Improvements and fixes

[davidmigloz]

• Improve handling of descriptions in SchemaGenerator
  • Trims all descriptions
  • Replaces \n by \n/// after trimming to avoid comments with an empty line at the end
• Use Future.value in middleware functions
  • Small performance improvement. Using Future.value Dart will create a new microtask event into the microtask queue instead of a new event into the event queue.
• Fix nullable property not taken into account in objects and enum
• Add possible values in enums descriptions
  • Edit: This is actually breaking the tests as we are modifying the spec content. Should I move this to the generator instead?
• Use request schema description when null requestBody description
• Allow to define global headers included in every request

cc @walsha2

[walsha2]

@davidmigloz yes, I would probably move this to the generator. Although, I do have a question:

Why are we re-documenting enum values in the doc strings. This seems redundant. Simply clicking on the type should take you to the enum definition (lives in its own file) that you can quickly inspect to see the values. I think this adds a lot of extra documentation that may be unnecessary and distracting, no?

[davidmigloz]

Currently, if the enum is defined as an inner schema, it is generated with type String.

Eg.

schemas:
  CreateCompletionRequest:
    type: object
    description: Request object for the Create completion endpoint.
    properties:
      model:
        description: &model_description |
          ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-...
        type: string
        enum:
          [
            "babbage-002",
            "davinci-002",
            "gpt-3.5-turbo-instruct",
            "text-davinci-003",
            "text-davinci-002",
            "text-davinci-001",
            "code-davinci-002",
            "text-curie-001",
            "text-babbage-001",
            "text-ada-001",
          ]

It will be converted into:

/// Factory constructor for CreateCompletionRequest
const factory CreateCompletionRequest({
  /// ID of the model to use. You can use the [List models](https://platform.openai.com/doc...
  required String model,
})

So, in this case, documenting the possible values is nice. I agree, that when using an actual enum it is redundant.

I've moved that logic to the generator and only for this specific case. If you define the enum as a separate schema (which by the way is broken at the moment), it won't document the enum values.

Let me know if that works for you.

[walsha2]

If you define the enum as a separate schema (which by the way is broken at the moment)

What do you mean by this? Maybe I am misunderstanding, but I generate enum schemas all the time from defined component schemas. Here is an example:

"components": {
  "schemas": {
    "Task": {
      "title": "Task",
      "enum": [
        "pending",
        "completed",
        "failed"
      ],
      "type": "string",
      "description": "An enumeration."
    },
  }
}

enum Task {
  @JsonValue('pending')
  inProgress,
  @JsonValue('completed')
  canceled,
  @JsonValue('failed')
  failed,
}

[davidmigloz]

I haven't dug into it yet, but if instead of this:

CreateCompletionRequest:
  type: object
  description: Request object for the Create completion endpoint.
  properties:
    model:
      description: ...
      type: string
      enum:
        [
          "babbage-002",
          "davinci-002",
          "gpt-3.5-turbo-instruct",
          "text-davinci-003",
          "text-davinci-002",
          "text-davinci-001",
          "code-davinci-002",
          "text-curie-001",
          "text-babbage-001",
          "text-ada-001",
        ]

I move it to its own schema:

CompletionModel:
  type: string
  enum:
    [
      "babbage-002",
      "davinci-002",
      "gpt-3.5-turbo-instruct",
      "text-davinci-003",
      "text-davinci-002",
      "text-davinci-001",
      "code-davinci-002",
      "text-curie-001",
      "text-babbage-001",
      "text-ada-001",
    ]
CreateCompletionRequest:
  type: object
  description: Request object for the Create completion endpoint.
  properties:
    model:
      $ref: "#/components/schemas/CompletionModel"

I get the following exception:

Unhandled exception:
'package:openapi_spec/src/open_api/index.freezed.dart': Failed assertion: line 10478 pos 13: 'values == null || ref == null': Cannot define both values and ref

I'll look into it in a bit.

[davidmigloz]

The issue seems to be that when dereferencing an enum the new _SchemaEnum will have both ref and values, which is not allowed by the assert.

I've removed the assert and it works as expected (but I guess it's not ideal), do you have a better suggestion?

[walsha2]

@davidmigloz I tested this out on a fairly complicated spec and everything looks good. My only comment is regarding "Add possible values in enums descriptions". Without more context regarding what benefit this adds, I think we should remove this change from this PR.

Let me know when you are ready for this to be merged and I will get it in.

[davidmigloz]

I've included a couple more fixes in the PR (let me know if it's getting too big 😅)

• Fix objects with additionalProperties=false generated as Map
• Fix objects defined as typedef not preserving description and nullable

[walsha2]

No this is great stuff! I really want to add mini tests composed of small API spec snippets that test individual cases and ensure that the generated code is proper. In time!

Let's get this merged in and see if we can close out some of the other issues and cut a new release before the weekend is out.

[davidmigloz]

Awesome!

Yeah, the small API spec snippets will really help.