diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 1352216..81b424b 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -5733,6 +5733,7 @@ components: INDIVIDUAL: '#/components/schemas/BrlBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' CadBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -5776,10 +5777,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/CadBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/CadBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6202,6 +6201,7 @@ components: INDIVIDUAL: '#/components/schemas/MyrBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' NgnBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -6245,10 +6245,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/NgnBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/NgnBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6571,50 +6569,28 @@ components: - $ref: '#/components/schemas/BaseWalletInfo' ExternalAccountInfoOneOf: oneOf: - - title: BRL Account - $ref: '#/components/schemas/BrlExternalAccountInfo' - - title: CAD Account - $ref: '#/components/schemas/CadExternalAccountInfo' - - title: DKK Account - $ref: '#/components/schemas/DkkExternalAccountInfo' - - title: EUR Account - $ref: '#/components/schemas/EurExternalAccountInfo' - - title: GBP Account - $ref: '#/components/schemas/GbpExternalAccountInfo' - - title: HKD Account - $ref: '#/components/schemas/HkdExternalAccountInfo' - - title: IDR Account - $ref: '#/components/schemas/IdrExternalAccountInfo' - - title: INR Account - $ref: '#/components/schemas/InrExternalAccountInfo' - - title: MXN Account - $ref: '#/components/schemas/MxnExternalAccountInfo' - - title: MYR Account - $ref: '#/components/schemas/MyrExternalAccountInfo' - - title: NGN Account - $ref: '#/components/schemas/NgnExternalAccountInfo' - - title: PHP Account - $ref: '#/components/schemas/PhpExternalAccountInfo' - - title: SGD Account - $ref: '#/components/schemas/SgdExternalAccountInfo' - - title: THB Account - $ref: '#/components/schemas/ThbExternalAccountInfo' - - title: USD Account - $ref: '#/components/schemas/UsdExternalAccountInfo' - - title: VND Account - $ref: '#/components/schemas/VndExternalAccountInfo' - - title: Spark Wallet - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' - - title: Lightning - $ref: '#/components/schemas/LightningExternalAccountInfo' - - title: Solana Wallet - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' - - title: Tron Wallet - $ref: '#/components/schemas/TronWalletExternalAccountInfo' - - title: Polygon Wallet - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' - - title: Base Wallet - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' + - $ref: '#/components/schemas/BrlExternalAccountInfo' + - $ref: '#/components/schemas/CadExternalAccountInfo' + - $ref: '#/components/schemas/DkkExternalAccountInfo' + - $ref: '#/components/schemas/EurExternalAccountInfo' + - $ref: '#/components/schemas/GbpExternalAccountInfo' + - $ref: '#/components/schemas/HkdExternalAccountInfo' + - $ref: '#/components/schemas/IdrExternalAccountInfo' + - $ref: '#/components/schemas/InrExternalAccountInfo' + - $ref: '#/components/schemas/MxnExternalAccountInfo' + - $ref: '#/components/schemas/MyrExternalAccountInfo' + - $ref: '#/components/schemas/NgnExternalAccountInfo' + - $ref: '#/components/schemas/PhpExternalAccountInfo' + - $ref: '#/components/schemas/SgdExternalAccountInfo' + - $ref: '#/components/schemas/ThbExternalAccountInfo' + - $ref: '#/components/schemas/UsdExternalAccountInfo' + - $ref: '#/components/schemas/VndExternalAccountInfo' + - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' + - $ref: '#/components/schemas/LightningExternalAccountInfo' + - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' + - $ref: '#/components/schemas/TronWalletExternalAccountInfo' + - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' + - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' discriminator: propertyName: accountType mapping: diff --git a/openapi.yaml b/openapi.yaml index 1352216..81b424b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5733,6 +5733,7 @@ components: INDIVIDUAL: '#/components/schemas/BrlBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' CadBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -5776,10 +5777,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/CadBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/CadBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6202,6 +6201,7 @@ components: INDIVIDUAL: '#/components/schemas/MyrBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' NgnBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -6245,10 +6245,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/NgnBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/NgnBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6571,50 +6569,28 @@ components: - $ref: '#/components/schemas/BaseWalletInfo' ExternalAccountInfoOneOf: oneOf: - - title: BRL Account - $ref: '#/components/schemas/BrlExternalAccountInfo' - - title: CAD Account - $ref: '#/components/schemas/CadExternalAccountInfo' - - title: DKK Account - $ref: '#/components/schemas/DkkExternalAccountInfo' - - title: EUR Account - $ref: '#/components/schemas/EurExternalAccountInfo' - - title: GBP Account - $ref: '#/components/schemas/GbpExternalAccountInfo' - - title: HKD Account - $ref: '#/components/schemas/HkdExternalAccountInfo' - - title: IDR Account - $ref: '#/components/schemas/IdrExternalAccountInfo' - - title: INR Account - $ref: '#/components/schemas/InrExternalAccountInfo' - - title: MXN Account - $ref: '#/components/schemas/MxnExternalAccountInfo' - - title: MYR Account - $ref: '#/components/schemas/MyrExternalAccountInfo' - - title: NGN Account - $ref: '#/components/schemas/NgnExternalAccountInfo' - - title: PHP Account - $ref: '#/components/schemas/PhpExternalAccountInfo' - - title: SGD Account - $ref: '#/components/schemas/SgdExternalAccountInfo' - - title: THB Account - $ref: '#/components/schemas/ThbExternalAccountInfo' - - title: USD Account - $ref: '#/components/schemas/UsdExternalAccountInfo' - - title: VND Account - $ref: '#/components/schemas/VndExternalAccountInfo' - - title: Spark Wallet - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' - - title: Lightning - $ref: '#/components/schemas/LightningExternalAccountInfo' - - title: Solana Wallet - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' - - title: Tron Wallet - $ref: '#/components/schemas/TronWalletExternalAccountInfo' - - title: Polygon Wallet - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' - - title: Base Wallet - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' + - $ref: '#/components/schemas/BrlExternalAccountInfo' + - $ref: '#/components/schemas/CadExternalAccountInfo' + - $ref: '#/components/schemas/DkkExternalAccountInfo' + - $ref: '#/components/schemas/EurExternalAccountInfo' + - $ref: '#/components/schemas/GbpExternalAccountInfo' + - $ref: '#/components/schemas/HkdExternalAccountInfo' + - $ref: '#/components/schemas/IdrExternalAccountInfo' + - $ref: '#/components/schemas/InrExternalAccountInfo' + - $ref: '#/components/schemas/MxnExternalAccountInfo' + - $ref: '#/components/schemas/MyrExternalAccountInfo' + - $ref: '#/components/schemas/NgnExternalAccountInfo' + - $ref: '#/components/schemas/PhpExternalAccountInfo' + - $ref: '#/components/schemas/SgdExternalAccountInfo' + - $ref: '#/components/schemas/ThbExternalAccountInfo' + - $ref: '#/components/schemas/UsdExternalAccountInfo' + - $ref: '#/components/schemas/VndExternalAccountInfo' + - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' + - $ref: '#/components/schemas/LightningExternalAccountInfo' + - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' + - $ref: '#/components/schemas/TronWalletExternalAccountInfo' + - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' + - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' discriminator: propertyName: accountType mapping: diff --git a/openapi/README.md b/openapi/README.md index c2e6f03..5426ce2 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -275,6 +275,72 @@ discriminator: BUSINESS: '#/components/schemas/BusinessCustomer' ``` +#### Discriminator placement: OneOf wrapper only + +The `discriminator` block must only appear on the **OneOf wrapper** schema, never on the base schema. If both the base and wrapper define a discriminator, Mintlify renders duplicate type options in the UI. + +```yaml +# ✅ Correct — discriminator on the OneOf wrapper only +# ExternalAccountInfoOneOf.yaml +oneOf: + - $ref: ./UsdExternalAccountInfo.yaml + - $ref: ./EurExternalAccountInfo.yaml +discriminator: + propertyName: accountType + mapping: + USD_ACCOUNT: ./UsdExternalAccountInfo.yaml + EUR_ACCOUNT: ./EurExternalAccountInfo.yaml + +# BaseExternalAccountInfo.yaml — NO discriminator here +type: object +properties: + accountType: + type: string +``` + +```yaml +# ❌ Wrong — discriminator on both base and wrapper causes duplicate rendering +# BaseExternalAccountInfo.yaml +type: object +properties: + accountType: + type: string +discriminator: # ← remove this + propertyName: accountType + mapping: ... +``` + +#### Titles must be inside the schema, not next to `$ref` + +In OpenAPI, properties that are siblings to `$ref` are ignored. A `title:` placed next to `$ref:` in a `oneOf` entry will be silently dropped, so Mintlify won't display it. + +Instead, place `title:` as the **first line** of the referenced schema file. + +```yaml +# ✅ Correct — title inside the referenced schema +# CustomerOneOf.yaml +oneOf: + - $ref: ./IndividualCustomer.yaml + - $ref: ./BusinessCustomer.yaml + +# IndividualCustomer.yaml +title: Individual Customer # ← title goes here +allOf: + - $ref: ./Customer.yaml + - ... +``` + +```yaml +# ❌ Wrong — title as $ref sibling is ignored by OpenAPI parsers +oneOf: + - title: Individual Customer # ← ignored + $ref: ./IndividualCustomer.yaml + - title: Business Customer # ← ignored + $ref: ./BusinessCustomer.yaml +``` + +When adding a new variant schema to a `oneOf`, always add a `title:` as the first line of the variant file. + #### Three-layer discriminator pattern We use a three-layer pattern for discriminated unions: diff --git a/openapi/components/schemas/common/CadBeneficiary.yaml b/openapi/components/schemas/common/CadBeneficiary.yaml index c3b5722..c3941bc 100644 --- a/openapi/components/schemas/common/CadBeneficiary.yaml +++ b/openapi/components/schemas/common/CadBeneficiary.yaml @@ -1,3 +1,4 @@ +title: Individual Beneficiary type: object required: - beneficiaryType diff --git a/openapi/components/schemas/common/NgnBeneficiary.yaml b/openapi/components/schemas/common/NgnBeneficiary.yaml index c3b5722..c3941bc 100644 --- a/openapi/components/schemas/common/NgnBeneficiary.yaml +++ b/openapi/components/schemas/common/NgnBeneficiary.yaml @@ -1,3 +1,4 @@ +title: Individual Beneficiary type: object required: - beneficiaryType diff --git a/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml b/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml index 916c001..7d92d34 100644 --- a/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml +++ b/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml @@ -8,10 +8,8 @@ allOf: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: ../common/CadBeneficiary.yaml - - title: Business Beneficiary - $ref: ../common/BusinessBeneficiary.yaml + - $ref: ../common/CadBeneficiary.yaml + - $ref: ../common/BusinessBeneficiary.yaml discriminator: propertyName: beneficiaryType mapping: diff --git a/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml b/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml index 5569873..8878b74 100644 --- a/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml +++ b/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml @@ -1,48 +1,26 @@ oneOf: -- title: BRL Account - $ref: ./BrlExternalAccountInfo.yaml -- title: CAD Account - $ref: ./CadExternalAccountInfo.yaml -- title: DKK Account - $ref: ./DkkExternalAccountInfo.yaml -- title: EUR Account - $ref: ./EurExternalAccountInfo.yaml -- title: GBP Account - $ref: ./GbpExternalAccountInfo.yaml -- title: HKD Account - $ref: ./HkdExternalAccountInfo.yaml -- title: IDR Account - $ref: ./IdrExternalAccountInfo.yaml -- title: INR Account - $ref: ./InrExternalAccountInfo.yaml -- title: MXN Account - $ref: ./MxnExternalAccountInfo.yaml -- title: MYR Account - $ref: ./MyrExternalAccountInfo.yaml -- title: NGN Account - $ref: ./NgnExternalAccountInfo.yaml -- title: PHP Account - $ref: ./PhpExternalAccountInfo.yaml -- title: SGD Account - $ref: ./SgdExternalAccountInfo.yaml -- title: THB Account - $ref: ./ThbExternalAccountInfo.yaml -- title: USD Account - $ref: ./UsdExternalAccountInfo.yaml -- title: VND Account - $ref: ./VndExternalAccountInfo.yaml -- title: Spark Wallet - $ref: ./SparkWalletExternalAccountInfo.yaml -- title: Lightning - $ref: ./LightningExternalAccountInfo.yaml -- title: Solana Wallet - $ref: ./SolanaWalletExternalAccountInfo.yaml -- title: Tron Wallet - $ref: ./TronWalletExternalAccountInfo.yaml -- title: Polygon Wallet - $ref: ./PolygonWalletExternalAccountInfo.yaml -- title: Base Wallet - $ref: ./BaseWalletExternalAccountInfo.yaml +- $ref: ./BrlExternalAccountInfo.yaml +- $ref: ./CadExternalAccountInfo.yaml +- $ref: ./DkkExternalAccountInfo.yaml +- $ref: ./EurExternalAccountInfo.yaml +- $ref: ./GbpExternalAccountInfo.yaml +- $ref: ./HkdExternalAccountInfo.yaml +- $ref: ./IdrExternalAccountInfo.yaml +- $ref: ./InrExternalAccountInfo.yaml +- $ref: ./MxnExternalAccountInfo.yaml +- $ref: ./MyrExternalAccountInfo.yaml +- $ref: ./NgnExternalAccountInfo.yaml +- $ref: ./PhpExternalAccountInfo.yaml +- $ref: ./SgdExternalAccountInfo.yaml +- $ref: ./ThbExternalAccountInfo.yaml +- $ref: ./UsdExternalAccountInfo.yaml +- $ref: ./VndExternalAccountInfo.yaml +- $ref: ./SparkWalletExternalAccountInfo.yaml +- $ref: ./LightningExternalAccountInfo.yaml +- $ref: ./SolanaWalletExternalAccountInfo.yaml +- $ref: ./TronWalletExternalAccountInfo.yaml +- $ref: ./PolygonWalletExternalAccountInfo.yaml +- $ref: ./BaseWalletExternalAccountInfo.yaml discriminator: propertyName: accountType mapping: diff --git a/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml b/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml index 0109b2b..dd99296 100644 --- a/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml +++ b/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml @@ -8,10 +8,8 @@ allOf: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: ../common/NgnBeneficiary.yaml - - title: Business Beneficiary - $ref: ../common/BusinessBeneficiary.yaml + - $ref: ../common/NgnBeneficiary.yaml + - $ref: ../common/BusinessBeneficiary.yaml discriminator: propertyName: beneficiaryType mapping: