From 5ff7e9543166bd3bb64627779750ecb43d475923 Mon Sep 17 00:00:00 2001 From: BrigittaK307 Date: Mon, 10 Aug 2026 11:56:07 +0300 Subject: [PATCH 1/2] added openapi experimental support docs --- .../openapi/generate-openapi-client.mdx | 109 ++++++++++++++++++ docs-js/features/openapi/overview.mdx | 2 +- 2 files changed, 110 insertions(+), 1 deletion(-) diff --git a/docs-js/features/openapi/generate-openapi-client.mdx b/docs-js/features/openapi/generate-openapi-client.mdx index 87fd00992a4..92919c120a5 100644 --- a/docs-js/features/openapi/generate-openapi-client.mdx +++ b/docs-js/features/openapi/generate-openapi-client.mdx @@ -215,6 +215,115 @@ With the approach of the SAP Cloud SDK OpenAPI generator this restriction might Given that you have multiple APIs, it can make sense to have the same function names in different APIs, e.g. `MyResource1Api.getAll()` and `MyResource2Api.getAll()`. The purpose of the `x-sap-cloud-sdk-operation-name` is to allow using duplicate names across APIs, while complying with the OpenAPI specification. +## OpenAPI 3.1 Support + +:::caution + +OpenAPI 3.1 support is an experimental feature. +Generated code may not be fully correct in all edge cases. +Report issues in the SAP Cloud SDK [GitHub repository](https://github.com/SAP/cloud-sdk-js/issues/new/choose). + +::: + +The SAP Cloud SDK generator accepts OpenAPI 3.1 specifications. +When you pass an OpenAPI 3.1 document, the generator emits a warning and proceeds with generation. +OpenAPI 2.0 and OpenAPI 3.0.x documents continue to work without any changes. + +### Supported OpenAPI 3.1 Schema Features + +The following JSON Schema 2020-12 keywords introduced in OpenAPI 3.1 are supported: + +#### Type arrays and nullable types + +In OpenAPI 3.1, a schema property can list multiple types as an array and express nullability by including `"null"` in the type array instead of the `nullable: true` flag used in 3.0. + +```yaml +# OpenAPI 3.1 – nullable string using type array +myProperty: + type: ['string', 'null'] +``` + +The generator maps this to the TypeScript union type `string | null`. + +#### `const` schemas + +A schema with a `const` keyword defines a single fixed value. +The generator serializes it as a TypeScript literal type. + +```yaml +status: + const: active +``` + +Generates: `'active'` (string literal) or a numeric literal for number values. + +#### Tuple schemas with `prefixItems` + +OpenAPI 3.1 replaces the `items` array syntax for tuples with `prefixItems`. +Each entry in `prefixItems` defines the schema for the item at that position. + +```yaml +coordinates: + type: array + prefixItems: + - type: number + - type: number + items: false +``` + +Generates the TypeScript tuple type `[number, number]`. +When `items` (or `additionalItems`) defines an additional schema, it becomes a rest element, for example `[string, ...number[]]`. + +#### `patternProperties` + +Pattern-based property constraints are merged into the additional properties type of the generated schema. + +#### Numeric `exclusiveMinimum` and `exclusiveMaximum` + +In OpenAPI 3.1 these keywords are numeric values instead of boolean modifiers. +The generator handles both representations transparently. + +#### Multiple examples with `examples` + +OpenAPI 3.1 replaces the singular `example` field with an `examples` array. +The generator reads `examples` when present and falls back to `example` for 3.0 documents. + +#### `contentEncoding` and `contentMediaType` + +A string schema that carries a `contentEncoding` (for example `base64`) is mapped to the TypeScript `Blob` type. + +A string schema that carries a `contentMediaType` is mapped to `Blob` only when the media type is binary. +Text-based media types remain as `string`: + +| `contentMediaType` value | Generated TypeScript type | +| :------------------------------- | :------------------------ | +| `application/vnd.apache.parquet` | `Blob` | +| `application/octet-stream` | `Blob` | +| `application/json` | `string` | +| `text/plain` | `string` | +| `application/problem+json` | `string` | + +Any `text/*` type and any type ending with `+json` or `+xml` is treated as text and stays as `string`. + +#### Sibling annotations alongside `$ref` + +OpenAPI 3.1 allows `description` and other annotations to appear next to a `$ref` on the same schema object. +The generator preserves those sibling annotations in the generated TypeScript types. + +#### Paths-optional documents + +OpenAPI 3.1 makes the `paths` field optional, allowing schemas-only or webhooks-only documents. +When a document has no paths, the generator produces the schema models without any API files. + +### Unsupported OpenAPI 3.1 Features + +The following OpenAPI 3.1 features are intentionally not represented in the generated client: + +- **Webhooks** — top-level `webhooks` are not generated as callable operations. +- **Reusable path items** — `components/pathItems` used as webhook targets are not generated. + +The generator logs a warning when it encounters either of these features in the input document. + ## npm Packages vs. Local clients The SAP Cloud SDK OpenAPI client generator generates TypeScript code. diff --git a/docs-js/features/openapi/overview.mdx b/docs-js/features/openapi/overview.mdx index 3f2dd773e4c..0eae9d64670 100644 --- a/docs-js/features/openapi/overview.mdx +++ b/docs-js/features/openapi/overview.mdx @@ -32,7 +32,7 @@ The [OpenAPI code generator](generate-openapi-client.mdx) is a [command line int - destinations - and other abstractions of the SAP Business Technology Platform. -It supports OpenAPI versions **2.0** and **3.0**. +It supports OpenAPI versions **2.0**, **3.0**, and **3.1** (experimental). You can use the OpenAPI generator to create a client library for any OpenAPI-based API service available on the [SAP Business Accelerator Hub](https://api.sap.com/) or found elsewhere in the Internet. If you encounter problems with the OpenAPI tooling of the SAP Cloud SDK, use our [support channels](/docs/overview/get-support) to get help. From b65d47e6bd0b9b823d8f491eaeb9a87cbb3c9d5d Mon Sep 17 00:00:00 2001 From: BrigittaK307 Date: Tue, 18 Aug 2026 12:58:41 +0300 Subject: [PATCH 2/2] Applied PR comments --- .../openapi/generate-openapi-client.mdx | 86 ------------------- docs-js/features/openapi/overview.mdx | 2 +- 2 files changed, 1 insertion(+), 87 deletions(-) diff --git a/docs-js/features/openapi/generate-openapi-client.mdx b/docs-js/features/openapi/generate-openapi-client.mdx index 92919c120a5..dd5c379a936 100644 --- a/docs-js/features/openapi/generate-openapi-client.mdx +++ b/docs-js/features/openapi/generate-openapi-client.mdx @@ -229,92 +229,6 @@ The SAP Cloud SDK generator accepts OpenAPI 3.1 specifications. When you pass an OpenAPI 3.1 document, the generator emits a warning and proceeds with generation. OpenAPI 2.0 and OpenAPI 3.0.x documents continue to work without any changes. -### Supported OpenAPI 3.1 Schema Features - -The following JSON Schema 2020-12 keywords introduced in OpenAPI 3.1 are supported: - -#### Type arrays and nullable types - -In OpenAPI 3.1, a schema property can list multiple types as an array and express nullability by including `"null"` in the type array instead of the `nullable: true` flag used in 3.0. - -```yaml -# OpenAPI 3.1 – nullable string using type array -myProperty: - type: ['string', 'null'] -``` - -The generator maps this to the TypeScript union type `string | null`. - -#### `const` schemas - -A schema with a `const` keyword defines a single fixed value. -The generator serializes it as a TypeScript literal type. - -```yaml -status: - const: active -``` - -Generates: `'active'` (string literal) or a numeric literal for number values. - -#### Tuple schemas with `prefixItems` - -OpenAPI 3.1 replaces the `items` array syntax for tuples with `prefixItems`. -Each entry in `prefixItems` defines the schema for the item at that position. - -```yaml -coordinates: - type: array - prefixItems: - - type: number - - type: number - items: false -``` - -Generates the TypeScript tuple type `[number, number]`. -When `items` (or `additionalItems`) defines an additional schema, it becomes a rest element, for example `[string, ...number[]]`. - -#### `patternProperties` - -Pattern-based property constraints are merged into the additional properties type of the generated schema. - -#### Numeric `exclusiveMinimum` and `exclusiveMaximum` - -In OpenAPI 3.1 these keywords are numeric values instead of boolean modifiers. -The generator handles both representations transparently. - -#### Multiple examples with `examples` - -OpenAPI 3.1 replaces the singular `example` field with an `examples` array. -The generator reads `examples` when present and falls back to `example` for 3.0 documents. - -#### `contentEncoding` and `contentMediaType` - -A string schema that carries a `contentEncoding` (for example `base64`) is mapped to the TypeScript `Blob` type. - -A string schema that carries a `contentMediaType` is mapped to `Blob` only when the media type is binary. -Text-based media types remain as `string`: - -| `contentMediaType` value | Generated TypeScript type | -| :------------------------------- | :------------------------ | -| `application/vnd.apache.parquet` | `Blob` | -| `application/octet-stream` | `Blob` | -| `application/json` | `string` | -| `text/plain` | `string` | -| `application/problem+json` | `string` | - -Any `text/*` type and any type ending with `+json` or `+xml` is treated as text and stays as `string`. - -#### Sibling annotations alongside `$ref` - -OpenAPI 3.1 allows `description` and other annotations to appear next to a `$ref` on the same schema object. -The generator preserves those sibling annotations in the generated TypeScript types. - -#### Paths-optional documents - -OpenAPI 3.1 makes the `paths` field optional, allowing schemas-only or webhooks-only documents. -When a document has no paths, the generator produces the schema models without any API files. - ### Unsupported OpenAPI 3.1 Features The following OpenAPI 3.1 features are intentionally not represented in the generated client: diff --git a/docs-js/features/openapi/overview.mdx b/docs-js/features/openapi/overview.mdx index 0eae9d64670..965ed3c4b4b 100644 --- a/docs-js/features/openapi/overview.mdx +++ b/docs-js/features/openapi/overview.mdx @@ -32,7 +32,7 @@ The [OpenAPI code generator](generate-openapi-client.mdx) is a [command line int - destinations - and other abstractions of the SAP Business Technology Platform. -It supports OpenAPI versions **2.0**, **3.0**, and **3.1** (experimental). +It supports OpenAPI versions **2.0**, **3.0**, and [**3.1** (experimental)](generate-openapi-client.mdx#openapi-31-support). You can use the OpenAPI generator to create a client library for any OpenAPI-based API service available on the [SAP Business Accelerator Hub](https://api.sap.com/) or found elsewhere in the Internet. If you encounter problems with the OpenAPI tooling of the SAP Cloud SDK, use our [support channels](/docs/overview/get-support) to get help.