共有コンポーネント

以下のコードは、API コントラクトの components オブジェクトに使用できる共有コンポーネントをまとめたものです。

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

以降は、個々のエントリをスキーマの別の場所で再利用することができるようになります。

参照の使用

OpenAPI 仕様では、ここで説明されているように、スキーマファイルで JSON 参照を使用できます。これにより、スキーマ内の異なる場所でオブジェクトを複数回定義する必要がなくなり、ファイルが小さくなり、管理が容易になります。

OAS とは対照的に、カスタム API では ローカル参照、つまり同じスキーマファイルで定義されたオブジェクトへの参照のみが許可されます。具体的には、そのような参照のみが可能です。

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

ただし、次のようなリモート参照と URL 参照は不可能です。

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

Important

例: 参照によるシステムクエリパラメーター siteId の使用:

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"