Shared Components

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

components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1
    locale:
      name: locale
      in: query
      description: The locale of the current request.
      required: false
      schema:
        type: string
        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.

important: 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'

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

components:
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1

paths:
  /customers:
    get:
      summary: Get loyalty information for customer
      operationId: getLoyaltyInfo
      parameters:
        - $ref: "#/components/parameters/siteId"