Shared Components

The following code summarizes the shared components that can be used for the components object in the API contract:

1components:
2  securitySchemes:
3    ShopperToken:
4      type: oauth2
5      flows:
6        authorizationCode:
7          authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
8          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
9          scopes: { list of available scopes }
10        clientCredentials:
11          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
12          scopes: { list of available scopes }
13    AmOAuth2:
14      type: oauth2
15      flows:
16        authorizationCode:
17          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
18          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
19          scopes: { list of available scopes }
20        clientCredentials:
21          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
22          scopes: { list of available scopes }
23  parameters:
24    siteId:
25      name: siteId
26      in: query
27      description: The site of the current request.
28      required: true
29      schema:
30        type: string
31        minLength: 1
32    locale:
33      name: locale
34      in: query
35      description: The locale of the current request.
36      required: false
37      schema:
38        type: string
39        minLength: 1

After that, the individual entries can be reused at different places of the schema.

Use of References

The OpenAPI specification allows the use of JSON References in schema files as described here. This avoids defining objects multiple times at different places in the schema, leading to files that are smaller and easier to maintain.

Contrary to OAS, Custom APIs only allow local references, that is, references to objects defined in the same schema file. Specifically, only such references are possible:

$ref: '#/components/parameters/sampleParam'

However, remote and URL references like these are not possible:

$ref: '../other_schema.yaml#/components/parameters/sampleParam'
$ref: 'https://www.example.org/other_schema.yaml#/components/parameters/sampleParam'

Important

Example: Using the system query parameter siteId via a reference:

1components:
2  parameters:
3    siteId:
4      name: siteId
5      in: query
6      description: The site of the current request.
7      required: true
8      schema:
9        type: string
10        minLength: 1

1paths:
2  /customers:
3    get:
4      summary: Get loyalty information for customer
5      operationId: getLoyaltyInfo
6      parameters:
7        - $ref: "#/components/parameters/siteId"