plaid / plaid-openapi Goto Github PK

API version 2020-09-14

plaid-openapi's Introduction

plaid-OpenAPI

Plaid uses the OpenAPI 3.0.0 specification to schematize our docs and to generate our supported client libraries. This provides for a consistent typing experience across our external interfaces. Below we have listed some examples and issues we have found when iterating on the specification.

Using the OpenAPI generator

You can find examples on the official OpenApiGenerator docs.

Generating Plaid supported client libraries

The following are approximate commands that we use to generate our 5 client libraries:

plaid-node

OpenAPI Generator version: 5.1.1

openapi-generator-cli generate -g typescript-axios  \
-i 2020-09-14.yml \
-o build/generated-node \
-p npmName=plaid,supportsES6=true,modelPropertyNaming=original \
-t local/templates/typescript-axios

plaid-python

OpenAPI Generator version: 6.1

openapi-generator-cli generate -g python \
-i 2020-09-14.yml \
-o build/generated-python \
-p packageName=plaid \
--global-property apiTests=false,modelTests=false \
-t templates/python

plaid-ruby

OpenAPI Generator version: 6.3

openapi-generator-cli generate -g ruby  \
-i 2020-09-14.yml \
-o build/generated-ruby \
--global-property=apiTests=false,modelTests=false,useAutoload=true  \
--library=faraday \
-p gemName=plaid,gemRequiredRubyVersion=">= 3.0.0" \
-t local/templates/ruby

plaid-java

OpenAPI Generator version: 5.1.1

openapi-generator-cli generate -g java \
-i 2020-09-14.yml \
-o build/generated-java \
--library=retrofit2 \
--global-property apiDocs=false,modelDocs=false,apiTests=false,modelTests=false \
-p artifactId=plaid,apiPackage=com.plaid.client.request,modelPackage=com.plaid.client.model,dateLibrary=java8 \
-t templates/java \
--type-mappings=BigDecimal=Double

plaid-go

OpenAPI Generator version: 5.2

openapi-generator-cli -g go \
-i 2020-09-14.yml \
-o build/plaid-go \
--global-property=apiTests=false,modelTests=false,apiDocs=false,modelDocs=false \
-t templates/go \
-p packageName=plaid,enumClassPrefix=true,

All template edits can be found on their corresponding in the /templates folder for the associated library.

Known issues with openapi-generator

The openapi-generator often uses different styles based on the language you are generating.

We found that we had to modify our mustache templates to get servers and securitySchemes working for some generators. If possible, try not to modify these templates as they cause breaking changes upon upgrading, but modifications might be necessary for cases like these.
Enums as used by Plaid are extensible; that is, the API may add new enum values at will. However, OpenAPI generator for some languages will enable enum validation by default. You must disable strict enum validation for responses in your generated libraries, or your users may experience crashes when encountering a newly-added enum value in a response.

plaid-openapi's People

Contributors

Stargazers

Watchers

plaid-openapi's Issues

Illegal schema found with non-object type combined with properties, no properties should be defined:

Hello,

I am getting below output while generating the client using openapiGenerate gradle plugin. Though the client is generating but why this log and its repetitive like 50 times

Illegal schema found with non-object type combined with properties, no properties should be defined:
 class StringSchema {
    class Schema {
allOf schema `null` containing multiple types (not model) is not supported at the moment.
allOf schema `null` containing multiple types (not model) is not supported at the moment.
allOf schema `null` containing multiple types (not model) is not supported at the moment.
        type: string
        format: null
        $ref: null
        description: The point at which the user exited the Link flow. One of the following values.
        title: null
        multipleOf: null
        maximum: null
        exclusiveMaximum: null
        minimum: null
        exclusiveMinimum: null
        maxLength: null
        minLength: null
        pattern: null
        maxItems: null
        minItems: null
        uniqueItems: null
        maxProperties: null
        minProperties: null
        required: null
        not: null
        properties: {requires_questions=class Schema {
            type: null
            format: null
            $ref: null
            description: User prompted to answer security questions
            required: null
            not: null
            properties: null
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }, institution_not_found=class Schema {
            type: null
            format: null
            $ref: null
            description: User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
            title: null
            multipleOf: null
            maximum: null
            exclusiveMaximum: null
            minimum: null
            exclusiveMinimum: null
            maxLength: null
            minLength: null
            pattern: null
            maxItems: null
            minItems: null
            uniqueItems: null
            maxProperties: null
            minProperties: null
            required: null
            not: null
            properties: null
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }}
        additionalProperties: null
        nullable: null
        readOnly: null
        writeOnly: null
        example: null
        externalDocs: null
        deprecated: null
        discriminator: null
        xml: null
    }
}

Below is the command I am using to generate the client

openapi-generator generate -g kotlin \                                                                                                                
-i 2020-09-14.yml \
-o build/generated-kotlin \
--library=jvm-okhttp3 \
--global-property apiDocs=false,modelDocs=false,apiTests=false,modelTests=false \
-p artifactId=plaid,apiPackage=com.plaid.client.request,modelPackage=com.plaid.client.model,dateLibrary=java8 \
-t teamplates/java \
--type-mappings=BigDecimal=Double

Rust?

Hey there! It's my understanding that OpenAPI-generator supports rust: has anyone tried with the Plaid API?

LinkTokenCreateRequestUser Nullable Fields

In object LinkTokenCreateRequestUser (line 12217..12270), there are several fields that are described as optional, but not marked nullable; specifically date_of_birth, phone_number_verified_time, and email_address_verified_time. This means values are provided when not desired from languages that have date/time types. I am updating C# library to set these to nullable for now, but it would be nice to see them fixed with the next update.

Related: viceroypenguin/Going.Plaid#102

AddressMatchScore title

Currently, the AddressMatchScore entity has a title of address. I have been using title when present to parse the entity names, due to some types having unusable entity names. Specifically, in this case, the address title seems out of place, and is creating a conflict with the Address entity.

Would it be possible to either delete the title or set it to a more appropriate value? Thanks.

re: viceroypenguin/Going.Plaid#113

NumbersIBANNullable is not compiling when generating kotlin client

When a kotlin plaid sdk is generated using openapi-generator, the class NumbersIBANNullable is generated as a data class and since this class is not having any properties it results in compilation error as below,

NumbersIBANNullable.kt: Data class must have at least one primary constructor parameter

Since, this class is not referenced from anywhere, just removing it solves the problem. Now, I am not sure if this is how it should be solved. So, raising it here to be solved accordingly.

Below is the command used to generate the client.

openapi-generator generate -g kotlin \                                                                                                                         ✘ INT
-i 2020-09-14.yml \
-o build/generated-kotlin \
--library=jvm-okhttp3 \
--global-property apiDocs=false,modelDocs=false,apiTests=false,modelTests=false \
-p artifactId=plaid,apiPackage=com.plaid.client.request,modelPackage=com.plaid.client.model,dateLibrary=java8 \
-t teamplates/java \
--type-mappings=BigDecimal=Double

Generate Python library with type hints

I tried to follow the instructions in the README to run openapi-generator-cli to generate a python library so that I can generate a version with type hints. I ran the example codesnippet (mostly)

java -jar openapi-generator-cli.jar generate -g python \
-i 2020-09-14.yml \
-o build/generated-python \
-p packageName=plaid \
--global-property apiTests=false,modelTests=false \
-t templates/python

and a python library was generated. I tried to use this library as a replacement for the library published from https://github.com/plaid/plaid-python but the generated library didn't match the interface of the published one (and the generated library had some minor syntax errors).

The generated library does have type hints, but the differences in behavior are causing me issues; including this error when making a transactions_sync request

plaid.exceptions.ApiValueError: Invalid content_type returned. Content_type='application/json; charset=utf-8' was returned when only {'application/json'} are defined for status_code=200

Are there other flags that should be passed to the generator to get a library more compatible with the published one/a working one with type hints?

DefaultUpdateWebhook and Item do not use the ItemId schema for their item_id fields

The #/components/schemas/DefaultUpdateWebhook and #/components/schemas/Item are not using the #/components/schemas/ItemId schema for their respective item_id fields. Since I'm assuming the reason ItemId has a schema at all is to be able to modify what an ItemId looks like in one place this might be worth fixing.

Discrepancy on HealthIncident object

Currently, the HealthIncident object (2020-09-14.yml, L21684) indicates that the end_date property is not nullable. However, querying for certain institutions (specifically "ins_3", among others) returns HealthIncident objects with a null value for end_date. I am correcting in my library manually for now, but it would be nice to see this fixed with the next update.

Invalid yaml

/income/verification/documents/download
/beta/credit/v1/bank_employment/get
/deposit_switch/get

All have API errors in their yaml

most can be fixed with indentation; the beta one has x-hidden-from-docs: true outside of a method, which means some tooling treats it as a method and crashes.

Enum Value bug

link The value here has an extra tab by accident. "non-taxable brokerage account\t"

Enum descriptions

The following enums do not have descriptions:

AccountSubtype
CountryCode
Products
BankTransferType
BankTransferStatus
BankTransferNetwork
BankTransferEventType (description for items, but not for enum itself)

While most of these are fairly self evident, it makes it more difficult to add documentation on generated code.

Patterns for strings where feasible

We use the OpenAPI schema to mock the Plaid API and generate responses for property-based testing. With some string fields (like account_id, item_id, and access_token) we had to add the patterns ourselves since any utf8 strings, including empty ones, are conformant to the definition and we didn't want to use up the testing time on unrealistic cases. Would it be possible to add patterns like [a-zA-Z0-9]{37}, access-(?:sandbox|development|production)-{insert uuid4 regex}, etc. for fields where possible? This would also help us know exactly what kind of output to expect from the API and when those outputs change format so that we can validate inputs more strictly and perform optimizations like adjusting string column lengths in our database.

`ProcessorHistoricalUpdateWebhook` spec error

The ProcessorHistoricalUpdateWebhook, defined here, has an invalid spec, according to the data actually provided. Specifically, it asserts that account_id is a required field of the object, but the data provided by the server for this webhook do not include the account_id. Please see the related issue for example.

related: viceroypenguin/Going.Plaid#203

Not a valid OpenAPI 3.0 Specification

I could not parse this spec using prance with the OpenAPI Spec Validator back end. IBM's OpenAPI Validator throws up 99 errors and 312 warnings as well (for obvious reasons I won't list them all here).

Date/Time field identification

For strong-typing fields, it is useful to identify which ones are date/datetime. However, I have found 5 ways to identify a datetime field and one for date fields, and one that is ambiguous, but seems to be generally datetime:

DateTime

If the format is date-time
If the description contains 2020-10-30T15:26:48Z
If the description contains 2018-04-12T03:32:11Z
If the description contains 2017-09-14T14:42:19.350Z
If the description contains YYYY-MM-DDTHH:mm:ssZ

Date

If the description contains yyyy-mm-dd / YYYY-MM-DD (but not THH:mm:ssZ)

Technically ambiguous

If the description contains ISO 8601, but none of the above strings as well.

Request: to have consistency in these fields, to identify all of them either by the format or by YYYY-MM-DD (or both). I can provide a list of object/fields to make your jobs easier if needed.

Institution Search 'AuthSupportedMethods' property mismatch

When I make a request to /institutions/search, and include {options: { include_auth_metadata: true } }, the response looks like this:

"institutions": [
        {
            "auth_metadata": {
                "supported_methods": {
                    "automated_micro_deposit": true,
                    "instant_auth": false,
                    "instant_match": true
                }
            },
....

Note that automated_micro_deposit comes back singular. However, in the generated code in https://github.com/plaid/plaid-ruby/blob/v14.2.0/lib/plaid/models/auth_supported_methods.rb, the property is named automated_micro_deposits (plural).

The docs also specify that the property should be plural.

Trying to upgrade from the v13 client to v14.

Apologies if this is in the incorrect spot - first time submitting an issue here!

#/components/schemas/Error/properties/suggested_action should be nullable

#/components/schemas/Error is often returned with a null value. Ergo, the openapi definition should declare it as nullable.

@@ -10204,6 +10204,7 @@ components:
         suggested_action:
           type: string
           description: Suggested steps for resolving the error
+          nullable: true
       required:
       - error_type
       - error_code

Here is an example response:

{
  "display_message": null,
  "documentation_url": "https://plaid.com/docs/?ref=error#asset-report-errors-and-warnings",
  "error_code": "PRODUCT_NOT_READY",
  "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
  "error_type": "ASSET_REPORT_ERROR",
  "request_id": "3IZMwzrx9klXK6n",
  "suggested_action": null
}

Sharing Your OpenAPI Story

Hello there. I'd love to work with y'all to share your OpenAPI story as part of the OpenAPI Initiative (OAI) - https://www.openapis.org/ -- ping me if interested.

Using generated Clojure library fails due to non-existent requires

I'm using openapi-generator v.7.5.0-snapshot (due to an issue I helped resolve) to generate a Plaid Clojure library. Sadly, generated Clojure libraries do not come with tests, so I'd either have to write them myself (tough, since the API is large) or just handle bugs as I encounter them when using the library in a side project I'm building.

I'm generating the library with the following command:
openapi-generator generate -g clojure -i 2020-09-14.yml -o ./build/plaid-clj -p projectName=plaid-clj,sortParamsByRequiredFlag=true

When I try to use the generated library in the side project, errors are returned due to non-existent spec namespaces being required in ./build/plaid-clj/src/plaid_clj/api/plaid.clj. When I looked into which specs were not being generated, I noticed models of simple types like "string" were not generated.

So far, I've been preprocessing the OpenAPI YAML spec (2020-09-14.yml) with a Python script and adding a key for whether a certain model is of a simple type, then only including requires for models for which that key is falsey. However, I'm wondering whether perhaps a regex or something else can be added to the OpenAPI YAML spec so that specs are also generated for simple types (since these models normally have a format associated with them). (This is basically what #60 is suggesting.) Otherwise, could you recommend a way forward?

dates, datetimes, tooling

👋 It looks like your dates and date-time entries are subtly breaking a tool I use json-schema-faker when used with JSONSchemaFaker.option({ useExamplesValue: true, useDefaultValue: true });

This is for two reasons I can tell

datetime being set where something should be date (at least according to openapi 3 spec at swagger.io)
date-time (correct OAS3 👍 ) having a "zulu-character terminated string" format without a . (this could well be a json-schema-faker support problem, as the example given in OpenAPI swagger 3 spec is 2017-07-21T17:32:28Z which does match your format.

'#/components/schemas/CreditCardLiability.last_payment_date' is actually nullable

We received a null value for this field in production even though it is not marked nullable: true.

Field next_payment_due_date in liabilities should be nullable

Thanks for your work! We use this spec to generate Haskell code and this helped us a lot!

We found a small issue, want to leave a report here.

According to docs field next_payment_due_date in liabilities product is not marked as nullable explicitly, but mention optionality in a description. In the wild real-world for fresh credit cards we receive null, so this should be reflected in this spec.

Documentation Bug

Submitting as an issue rather than PR due to auto-generated .yml file.

The documentation entry here for pop (Point of Purchase enum value for ACHClass) has the ` and the " backwards.

Incorrect title correction

The title property of these objects is blank. Removing these properties would be more accurate in these places.

plaid-openapi/2020-09-14.yml

Line 4481 in e19f479

title: ""

plaid-openapi/2020-09-14.yml

Line 5019 in e19f479

title: ""

plaid-openapi/2020-09-14.yml

Line 8674 in e19f479

title: ""

Kotlin generation fails with NPE

Using the 6.1.0 version of openapi-generator with the following command run in Java 17: java -jar openapi-generator-cli.jar generate -g kotlin -i https://raw.githubusercontent.com/plaid/plaid-openapi/master/2020-09-14.yml I get the following error:

[main] INFO  o.o.codegen.TemplateManager - writing file ./src/main/kotlin/org/openapi/models/DepositSwitchGetResponse.kt
Exception in thread "main" java.lang.RuntimeException: Could not generate model 'DepositSwitchGetResponse'
	at org.openapitools.codegen.DefaultGenerator.generateModels(DefaultGenerator.java:563)
	at org.openapitools.codegen.DefaultGenerator.generate(DefaultGenerator.java:912)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:465)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
Caused by: java.lang.NullPointerException: Null context for variable '.' on line 14
	at com.samskivert.mustache.Template.getValueIn(Template.java:288)
	at com.samskivert.mustache.Template.getValue(Template.java:224)
	at com.samskivert.mustache.Template.getValueOrDefault(Template.java:279)
	at com.samskivert.mustache.Mustache$VariableSegment.execute(Mustache.java:802)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:866)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:881)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:870)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:866)
	at com.samskivert.mustache.Template.executeSegs(Template.java:157)
	at com.samskivert.mustache.Mustache$IncludedTemplateSegment.execute(Mustache.java:774)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$InvertedSegment.execute(Mustache.java:910)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:881)
	at com.samskivert.mustache.Mustache$BlockSegment.executeSegs(Mustache.java:845)
	at com.samskivert.mustache.Mustache$SectionSegment.execute(Mustache.java:866)
	at com.samskivert.mustache.Template.executeSegs(Template.java:157)
	at com.samskivert.mustache.Template.execute(Template.java:134)
	at com.samskivert.mustache.Template.execute(Template.java:125)
	at org.openapitools.codegen.templating.MustacheEngineAdapter.compileTemplate(MustacheEngineAdapter.java:65)
	at org.openapitools.codegen.TemplateManager.write(TemplateManager.java:163)
	at org.openapitools.codegen.DefaultGenerator.processTemplateToFile(DefaultGenerator.java:1058)
	at org.openapitools.codegen.DefaultGenerator.processTemplateToFile(DefaultGenerator.java:1045)
	at org.openapitools.codegen.DefaultGenerator.generateModelDocumentation(DefaultGenerator.java:389)
	at org.openapitools.codegen.DefaultGenerator.generateModels(DefaultGenerator.java:560)
	... 4 more

and the code generator exits. I also tried with 6.1.1 and 7.0.0 snapshots and got the same result. Any help would be appreciated.

`instant_microdeposits_enabled` field missing from `LinkTokenCreateRequestAuth`

The instant_microdeposits_enabled field is missing from LinkTokenCreateRequestAuth definition in the OpenAPI spec, and by extension it is missing from the clients.

The Plaid Docs warn that this field must be set to false to disable Instant Micro-Deposits and the change logs for the OpenAPI specs mention it was added in 2020-09-14_1.426.0.

InvestmentAccountSubtype contains an integer 529 in it's enumerated values

Several types include the string "529", but InvestmentAccountSubtype omits the quotes so 529 is interpreted as an integer. This is technically incompatible with the string type.

OpenAPI2 (or non OpenAPI 3) support

Cross-linking as accidentally opened in plaid postman repo

plaid/plaid-postman#140

Mark fields as required

It seems that all the api endpoints always include all the fields in their responses, and in case no value is set for a given field null is used to denote that. In fact the typescript definition files show that. However, not all fields are marked as required in the OpenApi responses.

For example JWKPublicKey has no required fields in the spec, but all fields are required in the typescript definitions. Similar things happen to Holdings or Securities.

Missing Enum Value

object IncidentUpdate, property status. The list of values for this enum is missing the value SCHEDULED, which is a value possibly returned by the api.

Should the members of `RemovedTransaction` be required?

Hi, I'm not sure if this is a question, or a bug report, but I'm implementing the transaction sync process (in node/ts) and was wondering if the fields in RemovedTransaction should be marked as required.
Current definition:

export interface RemovedTransaction {
    /**
     * The ID of the removed transaction.
     * @type {string}
     * @memberof RemovedTransaction
     */
    transaction_id?: string;
    /**
     * The ID of the account of the removed transaction.
     * @type {string}
     * @memberof RemovedTransaction
     */
    account_id?: string;
}

As it stands, the types given by the typescript definition would allow an empty object to be returned, or an object with just an account id.

Currently valid:

removed: RemovedTransaction = {}; // valid
removed: RemovedTransaction = { account_id: "id" }; // valid
removed: RemovedTransaction = { transaction_id: "id" }; //valid

In the 3 above situations, I'm not sure how I would interpret what Plaid is trying to tell me.

Nullable fields in /asset_report/get

The /asset_report/get endpoint retrieves the Asset Report with required fields client_report_id, but I get null in response. Maybe this is due to custom data?

plaid / plaid-openapi Goto Github PK

plaid-openapi's Introduction

plaid-OpenAPI

Using the OpenAPI generator

Generating Plaid supported client libraries

plaid-node

plaid-python

plaid-ruby

plaid-java

plaid-go

Known issues with openapi-generator

plaid-openapi's People

Contributors

Stargazers

Watchers

Forkers

plaid-openapi's Issues

DateTime

Date

Technically ambiguous

Recommend Projects

Recommend Topics

Recommend Org