pension_plan_kit/.build/checkouts/Get/Sources/Get/DataLoader.swift:156:50: error: incorrect argument label in call (have ':didCreateTask:', expected ':taskIsWaitingForConnectivity:') handlers[task]?.delegate?.urlSession?(session, didCreateTask: task)

In Templates.swift, requestOperationIdExtension adds a private extension.

If generation creates separate files, the private extension is also in its own file Paths+Extensions which makes it inaccessible to use in other files.

• followup for #60

When looking at the generated output, I didn't get the feeling that the extension files were named very naturally.

For example, a file containing the StringCodingKey type is named Entities+CodingKey.swift which to me feels a bit disconnected. If I was naming it myself, I'd have gone with StringCodingKey.swift instead.

In the end, I decided to rename the all of the files to better reflect their contents:

Before|After ---|--- Entities+CodingKey.swift|StringCodingKey.swift Entities+AnyJSON.swift|AnyJSON.swift Paths+Extensions.swift|Paths.swift (actually options.paths.namespace)

WDYT @LePips ?

Edit: differs from the original to a single global override instead of individual properties and I forgot parameter types. I think that we can start with a global override and somebody can request this fine tuning later.

Introduce a config option to override the Swift type when they are parsed and written:

# schema
Pet:
  properties:
    id:
      type: string
    tag:
      type: string
      format: uuid

# config
swiftTypeOverrides:
  UUID: String # any occurrences of UUID are replaced with String, so `Pet.tag: String`

Config name open for improvement. Obviously, a developer might override to a type that cannot be decoded from/encoded to the original type, like UUID: Int or a type that does not exist, like UUID: qwerty. So, it is a developer responsibility to make sure that overriding types can be properly decoded/encoded and that they are a proper Swift type.

This can be further enhanced with imports as we should be trivially able to set an imported type after https://github.com/CreateAPI/CreateAPI/issues/85 is figured out. Using NaiveDate as an example removing the useNaiveDate option, we include the package as an import in the config and then set the type override:

# schema
Pet:
  properties:
    birth_date:
      type: string
      format: date

# config
swiftTypeOverrides:
  Date: NaiveDate # any occurrences of Date are replaced with NaiveDate

Obviously, imported objects should be expected to properly decode/encode but that's an implementation detail of the imported type.

• Depends on https://github.com/CreateAPI/CreateAPI/pull/135
• Closes https://github.com/CreateAPI/CreateAPI/issues/114

What

As described in #114, a Swift type override can be very powerful when working together with packages.dependencies and entites/paths.imports. The encoding/decoding caveats and developer responsibilities are in the issue.

This PR differs in the format now being:

dataTypeOverrides:
  data-type.format: SwiftType

The power comes from format being an open value on numbers, integers, and strings. Users can now use different built in types or create and import their own custom types for corresponding labels or a global override.

Examples:

• string.uuid: String
• number.float: Float80
• integer.Int64: Int, assuming useFixWidthIntegers = true and one wants to use Int32/Int
• string.password: MyPasswordType, assuming custom import
• string: MyStringType, assuming custom import

Using imports would require at least the following:

dataTypeOverrides:
  string.password: MyPasswordType
entities:
  import: MyPasswordType
packages:
  dependencies:
  - url: # MyPasswordTypeURL
  # rest of the dependency configuration

Again, it is a developer responsibility that these types are properly encoded/decoded, that they exist, and that it is proper within the context of their API.

TODO

• [x] Remove useNaiveDate
  • Leaving in for this implementation.

However, we can recommend NaiveDate and other packages that can enhance the experience in the documentation!

• [x] Interplay with useFixWidthIntegers.
  • ~~Should this or overrides take precedence?~~ Consensus reached to remove this and width types can be set here.
• [ ] Documentation
  • Overall example usage, noting that this is Advanced configuration.
• [x] Dictionary/array types (edited after some thought)
  • These are not "types" but "objects". This can be a future feature request. There can be a use case for this where: 1 - string.first_name: MyFirstNameType, custom format first_name 2 - An array object in the schema represents an array of first_name-formatted strings. So we want [MyFirstNameType]. This isn't configurable in the schema so this is something that developers should know within the context of their API.
• [ ] Split per entities/paths?
  • A use case I just thought of is where somebody would want to use their entities with something like string.uuid: String for convenience but when making calls that would then require an entity UUID as a parameter they want to enforce at runtime that the type is correct. This would increase to possibly three flags: globalDataTypeOverrides, entites.dataTypeOverrides, and paths.dataTypeOverrides. I say we ignore this and can be an enhancement later on if requested as it's somewhat similar to the individual property type override idea from the original issue.

Currently, we have a very vast amount of configuration options that must be included in the create-api.yaml file, but we also have some other options that also alter how the tool generates the output code that must be passed via CLI args. This includes the following:

• -s, --split - Split output into separate files
• --package <package> - Generates a complete package with a given name
• --module <module> - Use the following name as a module name
• --vendor <vendor> - Enabled vendor-specific logic (supported values: "github")
• --generate <generate> - Specifies what to generate (default: paths, entities)
• --filename-template <filename-template> - Example: "%0.generated.swift" will produce files with the following names: "Paths.generated.swift". (default: %0.swift)
• --entityname-template <entityname-template> - Example: "%0Generated" will produce entities with the following names: "EntityGenerated". (default: %0)

This means that there are two sources to dig through when altering configuration, which has the potential to cause confusion. It also makes it hard to invoke create-api from multiple different places without either copying the desired arguments or wrapping the invocation in a script.

Firstly, I'd like to understand if there is a good reason that these options should be separate to the options in the configuration file?

If we agree that isn't the case, I'd like to start making them available in the configuration instead.

Unless there is a good reason to keep the arguments as overrides to configuration options, my suggestion would be to deprecate them now and remove them in a future release. Printing a warning when used until they are removed.

• Closes #100

Before this change, to customise generation between structs, classes and classes marked as final, you would use the following options:

• isGeneratingStructs - to switch between structs and classes as the default
• isMakingClassesFinal - to make classes final if they were generated
• entitiesGeneratedAsClasses to provide overrides that should always generate as a class
• entitiesGeneratedAsStructs to provide overrides that should always generate as a struct

For the 0.1 release, we want to simplify this into two properties:

• defaultType - ([struct, class, finalClass]) the preferred type used for all entities when generating
• typeOverrides - A dictionary map of entity names and the type that they should be (from the list above)

This reduces overhead in the config file and also gives you more flexibility when choosing between class and final class.

In addition, we want to simplify the mutable property flags by going from the following:

• isGeneratingMutableClassProperties (true or false)
• isGeneratingMutableStructProperties (true or false)

to

• mutableProperties ([], [structs, classes], [structs] or [classes])

In #111 I also updated the config deserialiser so that it is capable of processing true, false or a single element when working with array/set based options. For example in YAML/JSON, mutableProperties: true would be considered the same as mutableProperties: [structs, classes].

I am just lost on how to actually consume my generated API.

What I've done is generate the the Entities.swift and Paths.swift drag an drop it into the project. Add Get and URLQueryEncoder via SPM. But now I'm faced with a bunch of Cannot find type 'api' in scope

Any info on what to do next would be nice. Thank you!

https://github.com/kean/CreateAPI/blob/87ba65d28a657ef7b94a758697cbf68d6075dbb9/Sources/CreateAPI/Generate.swift#L159-L160

In addition to not being thread-safe, JSONDecoder also does not appear to guarantee any explicit order of object keys.

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Order"
  },
  "paths": {
    "/container": {
      "get": {
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Container"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Container": {
        "type": "object",
        "required": null,
        "properties": {
          "propertyOne": {
            "type": "string"
          },
          "propertyTwo": {
            "type": "string"
          },
          "propertyThree": {
            "type": "string"
          },
          "propertyFour": {
            "type": "string"
          }
        }
      }
    }
  }
}

// Generated by Create API
// https://github.com/kean/CreateAPI
//
// swiftlint:disable all

import Foundation

public struct Container: Codable {
    public var propertyFour: String?
    public var propertyThree: String?
    public var propertyOne: String?
    public var propertyTwo: String?

    public init(propertyFour: String? = nil, propertyThree: String? = nil, propertyOne: String? = nil, propertyTwo: String? = nil) {
        self.propertyFour = propertyFour
        self.propertyThree = propertyThree
        self.propertyOne = propertyOne
        self.propertyTwo = propertyTwo
    }
}

struct StringCodingKey: CodingKey, ExpressibleByStringLiteral {
    private let string: String
    private var int: Int?

    var stringValue: String { return string }

    init(string: String) {
        self.string = string
    }

    init?(stringValue: String) {
        self.string = stringValue
    }

    var intValue: Int? { return int }

    init?(intValue: Int) {
        self.string = String(describing: intValue)
        self.int = intValue
    }

    init(stringLiteral value: String) {
        self.string = value
    }
}

The easiest workaround is to convert the .json spec to a .yaml spec beforehand.

Background

• #57

Description

Bundling everything into just Paths.swift and Entities.swift prevents the compiler from parallelising build tasks and results in bad compile times for larger projects.

Therefore bundling the source has little advantage compared to splitting into individual files (--split) so we should make this the default.

We're not ready to remove the option completely, likely we'll replace it with something like --no-split or --merge but we should put less emphasis on it.

The one time that I've found it useful is for predicting the output sources so that we can make efficient BuildToolPlugin's. But in the long run, I want to explore ways to break out the evaluation from the generation so that we could compute this ahead of time... Maybe..

I rather prefer Homebrew to install all my packages instead over Mint and of course over manual installation for every update. Could there be a Homebrew option for installation?

Hi, I'm working on a library for DeepL (it's amazing to see the capabilities of CreateAPI) and while doing so I encountered a bug that even seams to be present in the tests (https://github.com/CreateAPI/CreateAPI/blob/da8730b23dab769414229bb386b3dcc2a77d6e42/Tests/Support/Snapshots/edgecases-change-access-control/Sources/Paths/PathsFake.swift).

The problem is that CreateAPI generates a POST request using URLQueryEncoder.encode(body).percentEncodedQuery as the body, but it should be using the asQuery property instead. This causes the request to be incorrect because URLQueryEncoder.encode(body).percentEncodedQuery uses camelCase for the property names, but the expected format is snake_case, which asQuery correctly uses.

In the test the property pattern_without_delimiter incorrectly would be called patternWithoutDelimiter in the POST request.

So instead of https://github.com/CreateAPI/CreateAPI/blob/da8730b23dab769414229bb386b3dcc2a77d6e42/Tests/Support/Snapshots/edgecases-change-access-control/Sources/Paths/PathsFake.swift#L57

I would expect:

 Request(path: path, method: "POST", query: body?.asQuery, id: "testEndpointParameters") 

I have a case where the following example data:

{
    "note": {
        "text": "99 sheep <{{|t|1|}}> <{{|m|1|}}>",
        "tags": [
            {
                "id": 1,
                "key": "1234",
                "label": "some-tag"
            }
        ],
        "mentions": [
            {
                "id": 1,
                "key": "1234",
                "label": "some mention"
            }
        ]
    }
}

Results in the generated entity for "mentions" to be improperly named to Mantions, instead of Mention (note the typo):

public struct Note: Decodable {
  /// Example:
  ///
  /// [
  ///   {
  ///   "id" : 1,
  ///   "key" : "123432234",
  ///   "label" : "some-mention"
  ///   }
  /// ]
  public var mentions: [Mantions]?
  /// Example: []
  public var tags: [AnyJSON]?
  /// Example: "<{{|m|1|}}> some text"
  public var text: String?

  public struct Mantions: Decodable, Identifiable {
    public var id: Double?
    public var key: String?
    public var label: String?
  }
}

This also happens in another endpoint with the same name:

public struct GetResponse: Decodable {
    /// Example:
    ///
    /// [
    ///   {
    ///   "id" : 1,
    ///   "key" : "4321",
    ///   "label" : "some mention"
    ///   }
    /// ]
    public var mentions: [Mantions]?
    /// Example:
    ///
    /// [
    ///   {
    ///   "id" : 1,
    ///   "key" : "1234",
    ///   "label" : "some-tag"
    ///   }
    /// ]
    public var tags: [Tag]?

    public struct Mantions: Decodable, Identifiable {
        public var id: Double?
        public var key: String?
        public var label: String?
    }

    public struct Tag: Decodable, Identifiable {
        public var id: Double?
        public var key: String?
        public var label: String?
    }
}

I can work around it by renaming it to itself, so it skips the formatter:

rename:
  collectionElements:
    Mentions: Mention

$ create-api --version
0.1.1

Also tried on latest main since https://github.com/CreateAPI/CreateAPI/commit/da8730b23dab769414229bb386b3dcc2a77d6e42

• Closes https://github.com/CreateAPI/CreateAPI/issues/176

Implements individual property type override. This allows both general property naming and specific property type, mirroring the usage of rename.properties. I consider this an advanced feature, since this allows such fine control over single properties.

Overriding Optional

Since this is an advanced feature and by definition allows one to override the actual property type, it could be thought that his encompasses the entire type which includes whether it is an Optional.

For example, assume that Pet.tag would originally map to String?, but with the below:

entities:
  propertyTypeOverrides:
    Pet.tag: UUID

this would result in Pet.tag mapping to UUID, therefore making this required to the client. This can also happen the other way, making a non-optional property generate as an optional instead. This would also of course be a responsibility to the developer that the types can properly decode/encode.

I don't do this here (Optional is stable through the type override), however I think this should be a consideration.

While property schema datatype's can be overridden, I need to be able to override a single entity property type.

Context

The schema I am using has a string property that is represented by a string enum on the backend however isn't specified in the schema as an enum due to the complexity/time of rewriting the backend using that enum (along with a few others).

Essentially, I have my own Swift enum specified elsewhere and would like to use that instead to fill in gaps of the schema.

Currently the following would be generated:

struct MyItem {
	let itemType: String
}

What should come from generation:

struct MyItem {
	let itemType: MyItemType
}

Implementation

Introduce new config option entities.propertyTypeOverrides which represents a mapping of scheme properties to Swift types:

entities:
  propertyTypeOverrides:
    MyItem.itemType: MyItemType

This option would take precedence over the datatype override and would follow the same rule:

It is your responsibility to ensure that the replacement type conforms to Codable and can properly decode and encode to the original primitive type.

While my example is specifically for a String -> enum case, I think this can be helpful in other contexts.

• Closes https://github.com/CreateAPI/CreateAPI/issues/174

Sorts created properties, which go through their own independent renamings if applicable, instead of the raw keys.

Using useSwiftyPropertyNames: true and entities.sortPropertiesAlphabetically: true, the is- conversion is happening after the alphabetical sorting.

Example schema:

// ...
components:
  schemas:
    Pet:
      title: A pet title
      description: A pet description
      type: object
      required:
        - id
      properties:
        id:
          type: string
        likesMeat:
          type: boolean
        allergic:
          type: boolean

Generates the following:

public struct Pet: Codable {
    public var isAllergic: Bool?
    public var id: String
    public var isLikesMeat: Bool?

    // ...
}

It would be much more preferable if properties were properly sorted:

public struct Pet: Codable {
    public var id: String
    public var isAllergic: Bool?
    public var isLikesMeat: Bool?

    // ...
}

Additionally, it would probably be beneficial for an exclude list for useSwiftyPropertyNames as some property conversions may not be grammatically preferable, like in the above example.