[ADP-757] OpenAPI: x-violated-adp

指導原則

開發人員應該(SHOULD)直接在其 OpenAPI 規範中記錄任何違反 API 設計原則的情況。
應(SHOULD)使用 x-violated-adp 擴展來指定違反了哪條 ADP 規則以及原因。
x-violated-adp 擴展應(SHOULD)放置在 OpenAPI 規範的操作級別。
擴展內的描述在文件生成後不應(SHOULD NOT)向公眾公開。
每個違規應(SHOULD)包括:
- 被違反的 ADP 規則的 ID
- 清楚解釋為什麼需要違反該規則
開發人員應(SHOULD)考慮該違規是否表明需要更新 ADP 本身。

示例

yaml

openapi: 3.1.0
info:
  title: 示例 API
  version: 1.0.0
paths:
  /example:
    get:
      summary: 示例 GET 操作
      description: 此操作可能違反某些 ADP。
      x-violated-adp:
        - ruleId: "api-principle-rule-00001"
          description: "此設計違反了規則 00001,因為..."
        - ruleId: "api-principle-rule-00002"
          description: "此設計違反了規則 00002,因為..."
      responses:
        '200':
          description: 成功回應

TIP

💡 如果有充分理由，您應該將其反饋給此網站，以便為整個公司進行更改。

[ADP-757] OpenAPI: x-violated-adp ​

指導原則 ​

示例 ​

[ADP-757] OpenAPI: x-violated-adp

指導原則

示例