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

Purpose

This ADP provides guidance on how to document and justify exceptions to API design principles within OpenAPI specifications. It aims to maintain transparency and traceability when certain API design rules are violated for valid reasons.

Guidance

1. Developers SHOULD document any violations of API design principles directly in their OpenAPI specification.

2. The x-violated-adp extension SHOULD be used to specify which ADP rule is being violated and why.

3. The x-violated-adp extension SHOULD be placed at the operation level in the OpenAPI specification.

4. The description inside the extension SHOULD NOT be exposed to the public after document generation.

5. Each violation SHOULD include:

   • The ID of the violated ADP rule
   • A clear explanation of why the violation is necessary

6. Developers SHOULD consider whether the violation indicates a need for updating the ADP itself.

Example

openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Sample GET operation
      description: This operation may violate some ADP.
      x-violated-adp:
        - ruleId: "api-principle-rule-00001"
          description: "The design violates rule 00001 because..."
        - ruleId: "api-principle-rule-00002"
          description: "The design violates rule 00002 because..."
      responses:
        '200':
          description: Successful response

TIP

💡 If there's a good reason, you are expected to feedback it to this principle to change it for the whole company.