Merge pull request #90 from apiaddicts/develop

SebastianDT1 · web-flow · commit 6290b5385e34 · 2026-03-05T07:40:50.000-05:00
Develop
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.2] - 2026-03-05
+
+### Fixed
+    - OAR031 - Examples
+
 ## [1.3.1] - 2026-02-19
 
 ### Changed
diff --git a/pom.xml b/pom.xml
@@ -3,7 +3,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>org.apiaddicts.apitools.dosonarapi</groupId>
   <artifactId>sonaropenapi-rules-community</artifactId>
-  <version>1.3.1</version>
+  <version>1.3.2</version>
   <packaging>sonar-plugin</packaging>
 
   <name>SonarQube OpenAPI Community Rules</name>
diff --git a/src/main/java/apiaddicts/sonar/openapi/checks/examples/OAR031ExamplesCheck.java b/src/main/java/apiaddicts/sonar/openapi/checks/examples/OAR031ExamplesCheck.java
@@ -21,25 +21,60 @@ public class OAR031ExamplesCheck extends BaseCheck {
 
     private static final String EXAMPLE = "example";
     private static final String EXAMPLES = "examples";
+    private static final String SCHEMA = "schema";
+    private static final String PROPERTIES = "properties";
+    private static final String ITEMS = "items";
+
+    private static final String ERROR_RESPONSE = "OAR031.error-response";
 
     private final ExternalRefHandler handleExternalRef = new ExternalRefHandler();
 
     @Override
     public Set<AstNodeType> subscribedKinds() {
-        return ImmutableSet.of(OpenApi2Grammar.SCHEMA, OpenApi2Grammar.RESPONSES, OpenApi3Grammar.SCHEMA, OpenApi3Grammar.RESPONSES, OpenApi31Grammar.SCHEMA, OpenApi31Grammar.RESPONSES, OpenApi3Grammar.REQUEST_BODY, OpenApi31Grammar.REQUEST_BODY, OpenApi2Grammar.PATH, OpenApi3Grammar.PATH, OpenApi31Grammar.PATH);
+        return ImmutableSet.of(
+            OpenApi2Grammar.SCHEMA, OpenApi2Grammar.RESPONSES, OpenApi2Grammar.PARAMETER,
+            OpenApi3Grammar.SCHEMA, OpenApi3Grammar.RESPONSES, OpenApi3Grammar.PARAMETER,
+            OpenApi31Grammar.SCHEMA, OpenApi31Grammar.RESPONSES, OpenApi31Grammar.PARAMETER,
+            OpenApi3Grammar.REQUEST_BODY, OpenApi31Grammar.REQUEST_BODY, 
+            OpenApi2Grammar.PATH, OpenApi3Grammar.PATH, OpenApi31Grammar.PATH
+        );
     }
 
     @Override
     public void visitNode(JsonNode node) {
-        if (OpenApi2Grammar.PATH.equals(node.getType()) || OpenApi3Grammar.PATH.equals(node.getType()) || OpenApi31Grammar.PATH.equals(node.getType())) {
+        AstNodeType type = node.getType();
+        if (OpenApi2Grammar.PATH.equals(type) || OpenApi3Grammar.PATH.equals(type) || OpenApi31Grammar.PATH.equals(type)) {
             visitPathNode(node);
-        } else if (node.getType().equals(OpenApi2Grammar.RESPONSES) || node.getType().equals(OpenApi2Grammar.SCHEMA)) {
+        } else if (OpenApi2Grammar.PARAMETER.equals(type) || OpenApi3Grammar.PARAMETER.equals(type) || OpenApi31Grammar.PARAMETER.equals(type)) {
+            visitParameterNode(node);
+        } else if (type.equals(OpenApi2Grammar.RESPONSES) || type.equals(OpenApi2Grammar.SCHEMA)) {
             visitV2Node(node);
         } else {
             visitV3Node(node);
         }
     }
 
+    private void visitParameterNode(JsonNode node) {
+        handleExternalRef.resolve(node, resolved -> {
+            if (OpenApi2Grammar.PARAMETER.equals(resolved.getType())) {
+                JsonNode inNode = resolved.get("in");
+                if (!inNode.isMissing() && !"body".equals(inNode.getTokenValue())) {
+                    return;
+                }
+            }
+
+            JsonNode schema = resolved.get(SCHEMA);
+
+            boolean hasExample = !resolved.get(EXAMPLE).isMissing()
+                    || !resolved.get(EXAMPLES).isMissing()
+                    || (!schema.isMissing() && isSchemaCovered(schema));
+
+            if (!hasExample) {
+                addIssue(KEY, translate("OAR031.error-parameter"), handleExternalRef.getTrueNode(node));
+            }
+        });
+    }
+
     private void visitV2Node(JsonNode node) {
         AstNodeType type = node.getType();
         if (OpenApi2Grammar.RESPONSES.equals(type)) {
@@ -50,9 +85,15 @@ private void visitV2Node(JsonNode node) {
     }
 
     private void visitResponseV2Node(JsonNode node) {
-        if (node.get(EXAMPLES).isMissing()) {
-            addIssue(KEY, translate("OAR031.error-response"), node.key());
-        }
+        handleExternalRef.resolve(node, resolved -> {
+            JsonNode schemaNode = resolved.get(SCHEMA);
+            boolean hasExample = !resolved.get(EXAMPLES).isMissing()
+                    || (!schemaNode.isMissing() && isSchemaCovered(schemaNode));
+
+            if (!hasExample) {
+                addIssue(KEY, translate(ERROR_RESPONSE), handleExternalRef.getTrueNode(node.key()));
+            }
+        });
     }
 
     private void visitV3Node(JsonNode node) {
@@ -75,35 +116,58 @@ private void processResponses(JsonNode node, java.util.function.Consumer<JsonNod
 
     private void visitRequestBodyOrResponseV3Node(JsonNode node) {
         JsonNode content = node.at("/content");
+
         if (content.isMissing()) {
+            String errorKey = node.getType().equals(OpenApi3Grammar.REQUEST_BODY) ? "OAR031.error-request" : ERROR_RESPONSE;
+            addIssue(KEY, translate(errorKey), handleExternalRef.getTrueNode(node.key()));
             return;
         }
+
         for (JsonNode mediaTypeNode : content.propertyMap().values()) {
-            AstNodeType type = node.getType();
-            JsonNode schemaNode = mediaTypeNode.get("schema");
-            boolean hasSchemaExample = false;
-            if (schemaNode.getType().equals(OpenApi3Grammar.SCHEMA) && !schemaNode.get(EXAMPLE).isMissing()) {
-                hasSchemaExample = true;
-            }
-            if (!hasSchemaExample && mediaTypeNode.get(EXAMPLES).isMissing() && mediaTypeNode.get(EXAMPLE).isMissing()) {
-                if (type.equals(OpenApi3Grammar.REQUEST_BODY)) {
-                    addIssue(KEY, translate("OAR031.error-request"), handleExternalRef.getTrueNode(node.key()));
-                } else {
-                    addIssue(KEY, translate("OAR031.error-response"), handleExternalRef.getTrueNode(node.key()));
-                }
+            JsonNode schemaNode = mediaTypeNode.get(SCHEMA);
+            boolean hasExplicitExample = !mediaTypeNode.get(EXAMPLES).isMissing()
+                    || !mediaTypeNode.get(EXAMPLE).isMissing();
+
+            if (!hasExplicitExample && !isSchemaCovered(schemaNode)) {
+                String errorKey = node.getType().equals(OpenApi3Grammar.REQUEST_BODY) ? "OAR031.error-request" : ERROR_RESPONSE;
+                addIssue(KEY, translate(errorKey), handleExternalRef.getTrueNode(node.key()));
             }
         }
     }
 
+    private boolean isSchemaCovered(JsonNode schemaNode) {
+        if (schemaNode.isMissing()) return false;
+
+        return handleExternalRef.resolve(schemaNode, resolved -> {
+            if (!resolved.get(EXAMPLE).isMissing() || !resolved.get(EXAMPLES).isMissing()) {
+                return true;
+            }
+
+            JsonNode props = resolved.get(PROPERTIES);
+            if (!props.isMissing() && props.isObject()) {
+                return props.propertyMap().values().stream().anyMatch(this::isSchemaCovered);
+            }
+
+            JsonNode items = resolved.get(ITEMS);
+            if (!items.isMissing()) {
+                return isSchemaCovered(items);
+            }
+
+            return false;
+        });
+    }
+
     private void visitSchemaNode(JsonNode node) {
         JsonNode parentNode = (JsonNode) node.getParent().getParent();
 
         if (parentNode.getType().equals(OpenApi3Grammar.PARAMETER)) {
-            if (node.get(EXAMPLE).isMissing() && parentNode.get(EXAMPLE).isMissing() && parentNode.get(EXAMPLES).isMissing()) {
-                addIssue(KEY, translate("OAR031.error-parameter"), parentNode);
-            }
-        } else if (parentNode.getType().equals(OpenApi3Grammar.SCHEMA_PROPERTIES)
-                || parentNode.getType().toString().equals("BLOCK_MAPPING") || parentNode.getType().toString().equals("FLOW_MAPPING")) {
+            return;
+        }
+
+        if (parentNode.getType().equals(OpenApi3Grammar.SCHEMA_PROPERTIES)
+                || parentNode.getType().toString().equals("BLOCK_MAPPING") 
+                || parentNode.getType().toString().equals("FLOW_MAPPING")) {
+
             JsonNode schemaParent = (JsonNode) parentNode.getParent().getParent();
             if (schemaParent != null && !schemaParent.get("allOf").isMissing()) {
                 return;
@@ -140,11 +204,11 @@ private void visitPathNode(JsonNode node) {
     }
 
     private void visitSchemaNode2(JsonNode responseNode) {
-        JsonNode schemaNode = responseNode.value().get("schema");
+        JsonNode schemaNode = responseNode.value().get(SCHEMA);
         if (schemaNode.isMissing()) return;
 
         handleExternalRef.resolve(schemaNode, resolvedSchema -> {
-            JsonNode props = resolvedSchema.get("properties");
+            JsonNode props = resolvedSchema.get(PROPERTIES);
             if (props.isMissing() || !props.isObject()) return;
 
             props.propertyMap().forEach((key, propertyNode) -> {
@@ -154,4 +218,4 @@ private void visitSchemaNode2(JsonNode responseNode) {
             });
         });
     }
-}
+}
diff --git a/src/test/java/apiaddicts/sonar/openapi/checks/examples/OAR031ExamplesCheckTest.java b/src/test/java/apiaddicts/sonar/openapi/checks/examples/OAR031ExamplesCheckTest.java
@@ -26,6 +26,16 @@ public void verifyInV2WithoutExamples() {
         verifyV2("without-examples.yaml");
     }
 
+    @Test
+    public void verifyvalidV2ExternalRefs() {
+        verifyV2("externalref.yaml");
+    }
+
+    @Test
+    public void verifyInV2NestedProperties() {
+        verifyV2("nested-properties-examples.yaml");
+    }
+
     @Test
     public void verifyInV3() {
         verifyV3("valid.yaml");
@@ -41,6 +51,11 @@ public void verifyvalidV3ExternalRefs() {
         verifyV3("externalref.yaml");
     }
 
+    @Test
+    public void verifyInV3NestedProperties() {
+        verifyV3("nested-properties-examples.yaml");
+    }
+
     @Override
     public void verifyRule() {
         assertRuleProperties("OAR031 - Examples - Responses, Request Body, Parameters and Properties must have an example defined", RuleType.BUG, Severity.MAJOR, tags("examples"));
diff --git a/src/test/resources/checks/v2/examples/OAR031/externalref.yaml b/src/test/resources/checks/v2/examples/OAR031/externalref.yaml
@@ -0,0 +1,48 @@
+swagger: "2.0"
+info:
+  version: "1.0.0"
+  title: Example API
+host: api.example.com
+basePath: /v1
+schemes:
+  - https
+paths:
+  /users:
+    get:
+      responses:
+        200:
+          description: OK
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/User'
+        400:
+          $ref: >- # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+            https://raw.githubusercontent.com/apiaddicts/sonaropenapi-rules/refs/heads/master/src/test/resources/externalRef/OAR031.yaml#/components/responses/server_error_response
+  /users/{userId}:
+    get:
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          type: string
+      responses:
+        200:
+          description: A single user
+          schema:
+            $ref: '#/definitions/User'
+definitions:
+  User:
+    type: object
+    properties:
+      id:
+        type: string
+        example: "123"
+      name:
+        type: string
+        example: "John"
+  Error:
+    type: object
+    properties:
+      message: # Noncompliant {{OAR031: Properties must have an example defined}}
+        type: string
diff --git a/src/test/resources/checks/v2/examples/OAR031/nested-properties-examples.yaml b/src/test/resources/checks/v2/examples/OAR031/nested-properties-examples.yaml
@@ -0,0 +1,38 @@
+swagger: "2.0"
+info:
+  version: "1.0.0"
+  title: OAR031 Nested Example False Positive V2
+paths:
+  /profile:
+    put:
+      parameters:
+        - name: body
+          in: body
+          required: true
+          schema:
+            type: object
+            properties:
+              email:
+                type: string
+                example: "apellido@madrid.org"
+              telefono_fijo:
+                type: string
+                example: "600345345"
+              direccion:
+                type: object
+                properties:
+                  calle:
+                    type: string
+                    example: "Calle Indeterminada, 18"
+                  localidad:
+                    type: string
+                    example: "Madrid"
+                  provincia:
+                    type: string
+                    example: "Madrid"
+                  codigo_postal:
+                    type: string
+                    example: "28001"
+      responses:
+        200: # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+          description: OK
diff --git a/src/test/resources/checks/v2/examples/OAR031/valid.yaml b/src/test/resources/checks/v2/examples/OAR031/valid.yaml
@@ -8,7 +8,7 @@ paths:
       responses:
         204:
           description: No content
-        206: # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+        206:
           description: Pet list
           schema:
             $ref: '#/definitions/pets'
@@ -19,7 +19,7 @@ paths:
       parameters:
         - $ref: "#/parameters/id"
       responses:
-        200: # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+        200:
           description: One pet
           schema:
             $ref: "#/definitions/pet"
@@ -56,7 +56,7 @@ definitions:
         items:
           $ref: '#/definitions/pet'
 responses:
-  server_error_response: # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+  server_error_response:
     description: Default error response
     schema:
       type: object
diff --git a/src/test/resources/checks/v3/examples/OAR031/externalref.yaml b/src/test/resources/checks/v3/examples/OAR031/externalref.yaml
@@ -14,7 +14,7 @@ paths:
       summary: Get all users
       description: Returns a list of users.
       responses:
-        '200': # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+        '200':
           description: A JSON array of user objects
           content:
             application/json:
@@ -40,7 +40,7 @@ paths:
               name: Puppy
               type: dog
       responses:
-        '200': # Noncompliant {{OAR031: Responses must have one or more examples defined}}
+        '200':
           description: A single user object
           content:
             application/json:
diff --git a/src/test/resources/checks/v3/examples/OAR031/nested-properties-examples.yaml b/src/test/resources/checks/v3/examples/OAR031/nested-properties-examples.yaml
