Merge pull request #1771 from ballerina-platform/query-name-support

Add OpenAPI mapping support for query annotation with name field
ballerina-platform · Sep 19, 2024 · 8b7cbb3 · 8b7cbb3
2 parents 742e11e + 9d88386
commit 8b7cbb3
Show file tree

Hide file tree

Showing 9 changed files with 277 additions and 12 deletions.
diff --git a/ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/Constants.java b/ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/Constants.java
@@ -50,6 +50,7 @@ public final class Constants {
     public static final String ERROR_PAYLOAD = "ErrorPayload";
     public static final String TREAT_NILABLE_AS_OPTIONAL = "treatNilableAsOptional";
     public static final String HTTP_HEADER = "http:Header";
+    public static final String HTTP_QUERY = "http:Query";
     public static final String BYTE = "byte";
     public static final String XML = "xml";
     public static final String JSON = "json";

diff --git a/...api/src/main/java/io/ballerina/openapi/service/mapper/parameter/QueryParameterMapper.java b/...api/src/main/java/io/ballerina/openapi/service/mapper/parameter/QueryParameterMapper.java
@@ -36,6 +36,7 @@
 import java.util.Map;
 import java.util.Objects;
 
+import static io.ballerina.openapi.service.mapper.utils.MapperCommonUtils.getQueryName;
 import static io.ballerina.openapi.service.mapper.utils.MapperCommonUtils.unescapeIdentifier;
 
 /**
@@ -62,7 +63,8 @@ public QueryParameterMapper(ParameterNode parameterNode, Map<String, String> api
         Symbol parameterSymbol = additionalData.semanticModel().symbol(parameterNode).orElse(null);
         if (Objects.nonNull(parameterSymbol) && (parameterSymbol instanceof ParameterSymbol queryParameter)) {
             this.type = queryParameter.typeDescriptor();
-            this.name = unescapeIdentifier(queryParameter.getName().get());
+            String paramName = unescapeIdentifier(queryParameter.getName().get());
+            this.name = getQueryName(parameterNode, paramName);
             this.isRequired = queryParameter.paramKind().equals(ParameterKind.REQUIRED);
             this.description = apiDocs.get(queryParameter.getName().get());
             this.treatNilableAsOptional = treatNilableAsOptional;

diff --git a/...to-openapi/src/main/java/io/ballerina/openapi/service/mapper/utils/MapperCommonUtils.java b/...to-openapi/src/main/java/io/ballerina/openapi/service/mapper/utils/MapperCommonUtils.java
@@ -99,6 +99,8 @@
 import static io.ballerina.openapi.service.mapper.Constants.BALLERINA;
 import static io.ballerina.openapi.service.mapper.Constants.EMPTY;
 import static io.ballerina.openapi.service.mapper.Constants.HTTP;
+import static io.ballerina.openapi.service.mapper.Constants.HTTP_HEADER;
+import static io.ballerina.openapi.service.mapper.Constants.HTTP_QUERY;
 import static io.ballerina.openapi.service.mapper.Constants.HTTP_SERVICE_CONTRACT;
 import static io.ballerina.openapi.service.mapper.Constants.HYPHEN;
 import static io.ballerina.openapi.service.mapper.Constants.JSON_EXTENSION;
@@ -439,6 +441,14 @@ public static String unescapeIdentifier(String parameterName) {
     }
 
     public static String getHeaderName(ParameterNode parameterNode, String defaultName) {
+        return getParamName(HTTP_HEADER, parameterNode, defaultName);
+    }
+
+    public static String getQueryName(ParameterNode parameterNode, String defaultName) {
+        return getParamName(HTTP_QUERY, parameterNode, defaultName);
+    }
+
+    public static String getParamName(String paramTypeName, ParameterNode parameterNode, String defaultName) {
         NodeList<AnnotationNode> annotations = null;
         if (parameterNode instanceof RequiredParameterNode requiredParameterNode) {
             annotations = requiredParameterNode.annotations();
@@ -449,17 +459,17 @@ public static String getHeaderName(ParameterNode parameterNode, String defaultNa
             return defaultName;
         }
         for (AnnotationNode annotation : annotations) {
-            if (annotation.annotReference().toString().trim().equals("http:Header")) {
-                String valueExpression = getNameFromHeaderAnnotation(annotation);
-                if (valueExpression != null) {
+            if (annotation.annotReference().toString().trim().equals(paramTypeName)) {
+                String valueExpression = getNameFromParamAnnotation(annotation);
+                if (Objects.nonNull(valueExpression)) {
                     return valueExpression;
                 }
             }
         }
         return defaultName;
     }
 
-    private static String getNameFromHeaderAnnotation(AnnotationNode annotation) {
+    private static String getNameFromParamAnnotation(AnnotationNode annotation) {
         Optional<MappingConstructorExpressionNode> annotationRecord = annotation.annotValue();
         if (annotationRecord.isEmpty()) {
             return null;

diff --git a/docs/ballerina-to-oas/spec/spec.md b/docs/ballerina-to-oas/spec/spec.md
@@ -725,6 +725,26 @@ parameters:
       nullable: true
 ```
 
+The query parameter name in the schema is defaulted to the Ballerina parameter name. But this can be overridden using the `name` attribute in the `@http:Query` annotation.
+
+```ballerina
+service /api on new http:Listener(9090) {
+
+  resource function get path(@http:Query{name: "userName"} string param) {
+      // ...
+  }
+}
+```
+
+```yml
+parameters:
+  - name: userName
+    in: query
+    required: true
+    schema:
+      type: string
+```
+
 If the query parameter type is a `map` or `record` with `anydata` fields, then the query parameter schema is wrapped with `content` and `application/json` to indicate that the query parameter should be a JSON object which should be encoded properly.
 
 ```ballerina
@@ -836,6 +856,27 @@ parameters:
         nullable: true
 ```
 
+The header parameter name in the schema is defaulted to the Ballerina parameter name. But this can be overridden using the `name` attribute in the `@http:Header` annotation.
+
+```ballerina
+service /api on new http:Listener(9090) {
+
+  resource function get path(@http:Header{name: "xApiKeys"} string[] param) {
+      // ...
+  }
+}
+```
+
+```yml
+parameters:
+  - name: xApiKeys
+    in: header
+    schema:
+      type: array
+      items:
+        type: string
+```
+
 Additionally, the header parameter can be a closed `record` which contains the above basic types as fields. In that case, each field of this record represents a header parameter.
 
 ```ballerina
@@ -1029,7 +1070,7 @@ additionalProperties: false
 </td>
 </tr>
 <tr>
-<td><code>string:Char<code></td>
+<td><code>string:Char</code></td>
 <td>
 
 ```yml

diff --git a/gradle.properties b/gradle.properties
@@ -49,7 +49,7 @@ stdlibJwtVersion=2.13.0
 stdlibOAuth2Version=2.12.0
 
 # Stdlib Level 05
-stdlibHttpVersion=2.12.0
+stdlibHttpVersion=2.12.1-20240918-130700-9906dbe
 
 # Stdlib Level 06
 stdlibGrpcVersion=1.12.0

diff --git a/openapi-cli/src/test/java/io/ballerina/openapi/generators/openapi/QueryParameterTests.java b/openapi-cli/src/test/java/io/ballerina/openapi/generators/openapi/QueryParameterTests.java
@@ -98,6 +98,12 @@ public void testQueryscenario09() throws IOException {
         TestUtils.compareWithGeneratedFile(ballerinaFilePath, "query/query_scenario09.yaml");
     }
 
+    @Test(description = "Query parameters configured with name field")
+    public void testQueryscenario10() throws IOException {
+        Path ballerinaFilePath = RES_DIR.resolve("query/query_scenario10.bal");
+        TestUtils.compareWithGeneratedFile(ballerinaFilePath, "query/query_scenario10.yaml");
+    }
+
     @AfterMethod
     public void cleanUp() {
         TestUtils.deleteDirectory(this.tempDir);

diff --git a/openapi-cli/src/test/resources/ballerina-to-openapi/expected_gen/query/query_scenario10.yaml b/openapi-cli/src/test/resources/ballerina-to-openapi/expected_gen/query/query_scenario10.yaml
@@ -0,0 +1,174 @@
+openapi: 3.0.1
+info:
+  title: PayloadV
+  version: 0.0.0
+servers:
+  - url: "{server}:{port}/payloadV"
+    variables:
+      server:
+        default: http://localhost
+      port:
+        default: "9090"
+paths:
+  /query:
+    get:
+      operationId: getQuery
+      parameters:
+        - name: query0
+          in: query
+          schema:
+            type: string
+            default: ""
+        - name: q1
+          in: query
+          schema:
+            type: string
+        - name: query2
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+            default: []
+        - name: query3
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+            default:
+              - one
+              - two
+              - three
+        - name: query4
+          in: query
+          schema:
+            type: array
+            items:
+              type: integer
+              format: int64
+            default:
+              - 1
+              - 2
+              - 3
+        - name: query5
+          in: query
+          schema:
+            type: array
+            items:
+              type: number
+              format: float
+            default:
+              - 1
+              - 2.3
+              - 4.56
+        - name: query6
+          in: query
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  type: string
+                default:
+                  name: John
+                  city: London
+        - name: query7
+          in: query
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties:
+                    type: string
+                default:
+                  - name: John
+                    age: "25"
+                  - name: David
+                    age: "30"
+        - name: query8
+          in: query
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Record"
+                default:
+                  name: John
+                  address:
+                    number: 14/7
+                    streetName: 2nd cross street
+                    city: London
+        - name: query9
+          in: query
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  type: number
+                  format: float
+                default: {}
+        - name: query10
+          in: query
+          schema:
+            type: array
+            items:
+              type: boolean
+            default:
+              - true
+              - false
+              - true
+      responses:
+        "200":
+          description: Ok
+          content:
+            text/plain:
+              schema:
+                type: string
+        "400":
+          description: BadRequest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorPayload"
+components:
+  schemas:
+    ErrorPayload:
+      required:
+        - message
+        - method
+        - path
+        - reason
+        - status
+        - timestamp
+      type: object
+      properties:
+        timestamp:
+          type: string
+        status:
+          type: integer
+          format: int64
+        reason:
+          type: string
+        message:
+          type: string
+        path:
+          type: string
+        method:
+          type: string
+    Record:
+      required:
+        - address
+        - name
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          type: object
+          additionalProperties:
+            type: string
+      additionalProperties: false
diff --git a/openapi-cli/src/test/resources/ballerina-to-openapi/query/query_scenario10.bal b/openapi-cli/src/test/resources/ballerina-to-openapi/query/query_scenario10.bal
@@ -0,0 +1,31 @@
+import ballerina/http;
+
+listener http:Listener helloEp = new (9090);
+
+type Record record {|
+    string name;
+    map<string> address;
+|};
+
+const query1 = "query1";
+
+service /payloadV on helloEp {
+
+    resource function get query(
+            @http:Query{name: "query0"} string q0 = "",
+            @http:Query{name: query1} string q1 = string `"John"`,
+            @http:Query{name: "query2"} string[] q2 = [],
+            @http:Query{name: "query3"} string[] q3 = ["one", "two", "three"],
+            @http:Query{name: "query4"}  int[] q4 = [1, 2, 3],
+            @http:Query{name: "query5"} float[] q5 = [1, 2.3, 4.56],
+            @http:Query{name: "query6"} map<string> q6 = {"name": "John", "city": "London"},
+            @http:Query{name: "query7"} map<string>[] q7 = [{"name": "John", age: "25"},
+                {name: "David", age: "30"}],
+            @http:Query{name: "query8" } Record q8 = {name: "John", address: {number: "14/7",
+                streetName: "2nd cross street", city: "London"}},
+            @http:Query{name: "query9"} map<float> q9 = {},
+            @http:Query{name: "query10"} boolean[] q10 = [true, false, true]
+        ) returns string {
+        return "new";
+    }
+}