[ADP-752] OpenAPI: API 受眾
概述
- API 受眾用於識別 API 的預期用途並影響 API 管理。許多 ADP 設計是基於 API 的受眾而設計的。在 OpenAPI 中，我們使用擴展屬性(property)
x-audience來指定 API 受眾。
TIP
💡 一些 ADP 是基於受眾的。
INFO
💡 公共文件站點是根據受眾生成的。
OpenAPI 對 x-audience 的定義
yaml
#/info/x-audience:
type: string
x-extensible-enum:
- COMPONENT_INTERNAL
- BUSINESS_UNIT_INTERNAL
- COMPANY_INTERNAL
- PARTNER_EXTERNAL
- PUBLIC_EXTERNAL
description: |
API 的預期目標受眾。與設計和文件品質、審查、可發現性、
可變性和權限授予相關的標準有關。指導
- 必須(MUST)提供 x-audience，它是以下之一，按受眾規模排序:
| 值 | 描述 |
|---|---|
| COMPONENT_INTERNAL | API 使用是團隊特定的。 |
| BUSINESS_UNIT_INTERNAL | API 使用在同一業務單位內。 |
| COMPANY_INTERNAL | API 受眾針對公司內不同的業務單位。 |
| PARTNER_EXTERNAL | API 受眾是特定合作夥伴。 |
| PUBLIC_EXTERNAL | API 受眾是任何具有適當認證的人。 |
- 應該(SHOULD)在 API 級別(在
info對象中)包含 x-audience 屬性(property)，以指示 API 的整體預期受眾。 - 可以(MAY)在操作級別指定 x-audience，以覆蓋特定端點的 API 級別受眾。
示例
yaml
openapi: 3.0.1
info:
title: 示例 API
description: 這是一個示例 API，用於演示 x-audience 屬性(property)的使用。
version: 1.0.0
x-audience: COMPANY_INTERNAL
contact:
name: API 支持
url: http://www.example.com/support
email: support@example.com
paths:
/items:
get:
summary: 檢索項目列表
operationId: getItems
x-audience: PUBLIC_EXTERNAL
responses:
'200':
description: 項目列表
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Item'
/internal/items:
get:
summary: 檢索內部項目列表
operationId: getInternalItems
x-audience: COMPONENT_INTERNAL
responses:
'200':
description: 內部項目列表
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InternalItem'
components:
schemas:
Item:
type: object
properties:
id:
type: integer
name:
type: string
InternalItem:
type: object
properties:
id:
type: integer
name:
type: string
internalCode:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- ApiKeyAuth: []設計考慮
- 設計 API 時，考慮受眾優先級很重要。例如，為
PUBLIC_EXTERNAL使用設計的 API 是可以被內部團隊使用的。然而，在某些情況下，有必要為不同的受眾設計 API。在這種情況下，必須仔細設計它們，並為每個 API 分配唯一的operationId值，以區分它們的目的並確保正確使用。參見 應該提供 operationId。
注意: 在 API 級別只允許每個 API 規範有一個受眾。因此，較小的受眾群體有意包含在較廣的群體中，因此不需要額外聲明。如果您的 API 的部分有不同的目標受眾，我們建議沿著目標受眾拆分 API 規範 — 即使這會造成冗餘。