Skip to content

Latest commit

 

History

History
119 lines (96 loc) · 7.47 KB

CHANGELOG.adoc

File metadata and controls

119 lines (96 loc) · 7.47 KB
Raw

Changelog

8.x Series is based on OpenAPI 7.x+

  • The OpenAPI base now shifts to version 7 and Java 11.

  • It also shifts to a more strict interpretation of nullable (a field can have a null value) vs required (a field is required, but can be null or non null). A field is REQUIRED is it is marked as required, or if it is not nullable and has no default (otherwise Dart doesn’t know what to do with it).

  • We drop support for pre-Dart 2.12 code (i.e. non-null safe code)

  • We add the ability to drop deprecated APIs (additional property filter-deprecated-apis)

  • We add the ability to drop deprecated Models (additional property filter-deprecated-models)

If you want to support something like Person? then you need something like this:

   SomeClass:
     properties:
        person: # do not include a description or the API changes code generation
          nullable: true
          allOf:
            - $ref: "#/components/schemas/Person"

This text snippet does not change the API, you get a Person? person field. If you add a description, OpenAPI will automatically generate a new class which is outside of our control, and you will get a new class likely called SomeClassPerson so it can hold the description.

If you put nullable: true on the definition of the object itself, it inherently turns the object to always be nullable, so you get things like List<Person?> people.

7.x Series is based on OpenAPI 6.2+

The OpenAPI crew broke the API in weird ways in 6.2, so we go to a new major revision for supporting OpenAPI 6.2.

  • 7.2 - Support for Dio5, Support for OpenAPI 6.4.0, start dropping support for Dart < 2.12. Add an additional property useDio5=true.

  • 7.1 - No new functionality, just operating against 6.2.1

Note
 in the next release we will be dropping support for the old-style nullable APIs to simplify the code base.

6.x Series is based on OpenAPI 6

  • 6.3 - fix issue with required parameters (broken by 6.2), adding back support for inheritance broken by 6.1 upgrade. Samples for inheritance now included in general testing and release pipeline, along with Dart test.

  • 6.2 - migrate default lists and maps back to 5.x style. DO NOT USE

    • The 6.1 style of using const cause a lot of breakage and a difficult to use API. Where before it would set default list and map parameters such as Customer({this.listField = const []}), this will change back to Customer({List<X>? listField}) : this.listField = listField ?? []. This will let these fields be modified easily. Dart provides no way of ascertaining if a field is a constant.

  • 6.1 - migrate to the 6.0.1 version of OpenAPI

    • move to Java 11, swap to Kotlin. This is advertised as a breaking change and has led to some classes changing their names, adding new classes which didn’t exist before. This is a significant rewrite and retest of the functionality so we encourage people to report bugs and issues to us.

    • fields that are marked as required in the OpenAPI but have default values are not required in constructors (Dart fields with default values cannot be required)

    • previously required = non-null, !required = non-null. This behaviour has been refined. In Dart terms, it does not make sense for optional fields to not be nullable, so that remains, but required fields can now be nullable as long as they have a default value (or are a list or map).

    • required fields are now required - so if they aren’t in the incoming JSON data we will throw a serialisation error. Optional fields if they are empty or null will not be sent (unless the generateNullValuesToJson additional property is used, in which case fields will always be be added).

    • numeric fields are no longer "cast", they are always converted to their respective variants, toInt() or toDouble() - down through lists and so forth.

    • arrays and maps which have the special provided default values are always const following Dart’s requirements around constructors. This means you cannot "add" to them - i.e. create a model object and then add to the items in of the lists. If you wish to do this, you must provide a non-const value for the Map or List in the constructor.

5.x Series is based on OpenAPI 5.2.1 and below

  • 5.13 - ability to disable the copyWith generation (see above)

  • 5.12 - contributed fixes for inherited types (via https://github.com/roald-di)

  • 5.11 - fix date/datetime strings in queries to not be encoded. Updated to use 5.2.1 of OpenAPI. Fixed a bunch of templating issues that arose because of it.

  • 5.10 - removal of an unnecessary date/time typecast for null safety

  • 5.9 - fix for null safe 2d APIs (via PiotrMitkowski)

  • 5.8 - slew of different fixes for the generator from different people, particular thanks to NANASHI0X74 for sticky ones!

    1. 5.7 - includes fix for enums that contain spaces

  • 5.5 - this is a release focused on form, multi-part uploads, file uploads and downloads and enhancing the parameters as lodged in a couple of tickets. This release deletes unused models from Inline form models.

  • 5.4 - change the equals method to use a local variable called __other instead of other as when a class had an other property, the equals would break.

  • 5.3 - AnyOf support contribution by Łukasz Wiśniewski (https://github.com/vishna) and a resolution of the application/octet-stream issue where binary data is now returned as an ApiResponse (always).

  • 5.2 - this version addresses issues with complex codegen. It assumes that by default List and Map entries will be non null for null safe support.

  • 5.1 - this addresses the issues of a non-required POST body. It does not address the issue of complex tree structures of models as yet, this will come in 5.2.

  • 5.0 - is a significant departure and you will need to use the public Dart tool to migrate your code https://pub.dev/packages/openapi_migrate/versions/1.0.0 It allows the use of null safe code by adding in the extra additionalProperty nullSafe. It will also allow you to assume (and ensure defaults are set) null safety for all arrays that are otherwise not declared such in your OpenAPI yaml (by making them empty arrays) by the use of nullSafe-array-default.

It is recommended for 5.0 that you do an intermediate step and regenerate your existing code without these null safe functions turned on, and use the openapi_migrate tool on your code. Its likely you will need to run it multiple times to catch everything. When you are ready to move your whole project to null safety, you will be able to regenerate your API with the additionalProperty flags and then do the normal dart migrate process. We are doing this with our codebase over at FeatureHub (https://featurehub.io).

Another significant departure for 5.0 is that it enforces return vaulues - you cannot return a status code from an API that is not declared in your OpenAPI.

  • 4.2 - if you directly use the Type Transformers for enums, this is a breaking change. They have changed to extensions and have been slightly remodeled based on Robert’s inlining work. The whole deserialisation mechanism has changed particluarly for lists and maps because it wasn’t able to cope more than one level deep with lists and maps (issue #19). The date format now serialises directly properly, but not in lists.

  • 4.1 - support for OpenAPI v5, released 2020/12/21. Next release will support null types in Dart. Please note that with the move to 4.1, form models are by default NOT generated, so your parameters for methods calling forms won’t work. You need to set a global property called skipFormModels to false. In Maven this is in the configuration