FINERACT-2353: openAPI definition does not expose required GET parameters (#5025)

fineract-provider/src/main/java/org/apache/fineract/infrastructure/dataqueries/api/RunreportsApiResource.java

@@ -39,10 +39,10 @@ import jakarta.ws.rs.core.MultivaluedMap;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.UriInfo;
 import lombok.RequiredArgsConstructor;
-import org.apache.commons.lang3.StringUtils;
 import org.apache.fineract.infrastructure.core.api.ApiParameterHelper;
 import org.apache.fineract.infrastructure.core.exception.PlatformServiceUnavailableException;
 import org.apache.fineract.infrastructure.dataqueries.data.ReportExportType;
+import org.apache.fineract.infrastructure.dataqueries.data.ReportParameters;
 import org.apache.fineract.infrastructure.dataqueries.service.ReadReportingService;
 import org.apache.fineract.infrastructure.report.provider.ReportingProcessServiceProvider;
 import org.apache.fineract.infrastructure.report.service.ReportingProcessService;
@@ -54,7 +54,7 @@ import org.springframework.stereotype.Component;
 
 @Path("/v1/runreports")
 @Component
-@Tag(name = "Run Reports")
+@Tag(name = "Run Reports", description = "API for executing predefined reports with dynamic parameters")
 @RequiredArgsConstructor
 public class RunreportsApiResource {
 
@@ -68,14 +68,16 @@ public class RunreportsApiResource {
     @Path("/availableExports/{reportName}")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Return all available export types for the specific report", description = "Returns the list of all available export types.")
+    @Operation(summary = "Return all available export types for the specific report", description = "Returns the list of all available export types for a given report.")
     @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ReportExportType.class)))) })
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ReportExportType.class)))),
-    public Response retrieveAllAvailableExports(@PathParam("reportName") @Parameter(description = "reportName") final String reportName,
+            @ApiResponse(responseCode = "400", description = "Bad Request - Invalid report name or parameters"),
+            @ApiResponse(responseCode = "500", description = "Internal Server Error") })
+    public Response retrieveAllAvailableExports(
+            @PathParam("reportName") @Parameter(description = "Name of the report to get available export types for", example = "Client Listing", required = true) final String reportName,
             @Context final UriInfo uriInfo,
-            @DefaultValue("false") @QueryParam(IS_SELF_SERVICE_USER_REPORT_PARAMETER) @Parameter(description = IS_SELF_SERVICE_USER_REPORT_PARAMETER) final boolean isSelfServiceUserReport) {
+            @DefaultValue("false") @QueryParam(IS_SELF_SERVICE_USER_REPORT_PARAMETER) @Parameter(description = "Indicates if this is a self-service user report", example = "false") final boolean isSelfServiceUserReport) {
 
-        validateReportName(reportName);
         MultivaluedMap<String, String> queryParams = new MultivaluedStringMap();
         queryParams.putAll(uriInfo.getQueryParameters());
 
@@ -93,43 +95,56 @@ public class RunreportsApiResource {
     @Path("{reportName}")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON, "text/csv", "application/vnd.ms-excel", "application/pdf", "text/html" })
-    @Operation(summary = "Running a Report", description = "This resource allows you to run and receive output from pre-defined Apache Fineract reports.\n"
+    @Operation(summary = "Run a predefined report", description = ReportParameters.FULL_DESCRIPTION)
-            + "\n" + "Reports can also be used to provide data for searching and workflow functionality.\n" + "\n"
-            + "The default output is a JSON formatted \"Generic Resultset\". The Generic Resultset contains Column Heading as well as Data information. However, you can export to CSV format by simply adding \"&exportCSV=true\" to the end of your URL.\n"
-            + "\n"
-            + "If Pentaho reports have been pre-defined, they can also be run through this resource. Pentaho reports can return HTML, PDF or CSV formats.\n"
-            + "\n"
-            + "The Apache Fineract reference application uses a JQuery plugin called stretchy reporting which, itself, uses this reports resource to provide a pretty flexible reporting User Interface (UI).\n\n"
-            + "\n" + "\n" + "Example Requests:\n" + "\n" + "runreports/Client%20Listing?R_officeId=1\n" + "\n" + "\n"
-            + "runreports/Client%20Listing?R_officeId=1&exportCSV=true\n" + "\n" + "\n"
-            + "runreports/OfficeIdSelectOne?R_officeId=1&parameterType=true\n" + "\n" + "\n"
-            + "runreports/OfficeIdSelectOne?R_officeId=1&parameterType=true&exportCSV=true\n" + "\n" + "\n"
-            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=HTML&R_officeId=1\n"
-            + "\n" + "\n"
-            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=XLS&R_officeId=1\n"
-            + "\n" + "\n"
-            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=CSV&R_officeId=1\n"
-            + "\n" + "\n"
-            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=PDF&R_officeId=1")
     @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RunreportsApiResourceSwagger.RunReportsResponse.class))) })
+            @ApiResponse(responseCode = "200", description = "OK - Report executed successfully", content = @Content(schema = @Schema(implementation = RunreportsApiResourceSwagger.RunReportsResponse.class))),
-    public Response runReport(@PathParam("reportName") @Parameter(description = "reportName") final String reportName,
+            @ApiResponse(responseCode = "400", description = "Bad Request - Missing or invalid parameters"),
+            @ApiResponse(responseCode = "401", description = "Unauthorized - Not authorized to run this report"),
+            @ApiResponse(responseCode = "500", description = "Internal Server Error") })
+    public Response runReport(
+            @PathParam("reportName") @Parameter(description = "The name of the report to execute (e.g., 'Client Listing', 'Expected Payments By Date')", example = "Client Listing", required = true) final String reportName,
             @Context final UriInfo uriInfo,
-            @DefaultValue("false") @QueryParam(IS_SELF_SERVICE_USER_REPORT_PARAMETER) @Parameter(description = IS_SELF_SERVICE_USER_REPORT_PARAMETER) final boolean isSelfServiceUserReport) {
 
-        validateReportName(reportName);
+            @DefaultValue("false") @QueryParam(IS_SELF_SERVICE_USER_REPORT_PARAMETER) @Parameter(description = "Whether this is a self-service user report", example = "false") final boolean isSelfServiceUserReport,
 
+            @DefaultValue("false") @QueryParam("exportCSV") @Parameter(description = "Set to true to export results as CSV", example = "false") final Boolean exportCSV,
+
+            @DefaultValue("false") @QueryParam("parameterType") @Parameter(description = "Indicates if this is a parameter type request", example = "false") final Boolean parameterType,
+
+            @QueryParam("output-type") @Parameter(description = "Output format type (HTML, XLS, CSV, PDF)", example = "HTML") final String outputType,
+
+            @QueryParam("R_officeId") @Parameter(description = "Office ID filter", example = "1") final String rOfficeId,
+
+            @QueryParam("R_loanOfficerId") @Parameter(description = "Loan officer ID filter", example = "5") final String rLoanOfficerId,
+
+            @QueryParam("R_fromDate") @Parameter(description = "Start date filter (yyyy-MM-dd)", example = "2023-01-01") final String rFromDate,
+
+            @QueryParam("R_toDate") @Parameter(description = "End date filter (yyyy-MM-dd)", example = "2023-12-31") final String rToDate,
+
+            @QueryParam("R_currencyId") @Parameter(description = "Currency ID filter", example = "USD") final String rCurrencyId,
+
+            @QueryParam("R_accountNo") @Parameter(description = "Account number filter", example = "00010001") final String rAccountNo) {
+
+        return processReportRequest(reportName, uriInfo, isSelfServiceUserReport);
+    }
+
+    public Response runReport(final String reportName, final UriInfo uriInfo, final boolean isSelfServiceUserReport) {
+
+        return processReportRequest(reportName, uriInfo, isSelfServiceUserReport);
+    }
+
+    private Response processReportRequest(final String reportName, final UriInfo uriInfo, final boolean isSelfServiceUserReport) {
         MultivaluedMap<String, String> queryParams = new MultivaluedStringMap();
         queryParams.putAll(uriInfo.getQueryParameters());
 
-        final boolean parameterType = ApiParameterHelper.parameterType(queryParams);
+        final boolean parameterTypeValue = ApiParameterHelper.parameterType(queryParams);
 
-        checkUserPermissionForReport(reportName, parameterType);
+        checkUserPermissionForReport(reportName, parameterTypeValue);
 
         // Pass through isSelfServiceUserReport so that ReportingProcessService implementations can use it
         queryParams.putSingle(IS_SELF_SERVICE_USER_REPORT_PARAMETER, Boolean.toString(isSelfServiceUserReport));
 
-        String reportType = readExtraDataAndReportingService.getReportType(reportName, isSelfServiceUserReport, parameterType);
+        String reportType = readExtraDataAndReportingService.getReportType(reportName, isSelfServiceUserReport, parameterTypeValue);
         ReportingProcessService reportingProcessService = reportingProcessServiceProvider.findReportingProcessService(reportType);
         if (reportingProcessService == null) {
             throw new PlatformServiceUnavailableException("err.msg.report.service.implementation.missing",
@@ -148,30 +163,4 @@ public class RunreportsApiResource {
             }
         }
     }
-
-    /**
-     * Validates report name to prevent SQL injection attacks.
-     *
-     * @param reportName
-     *            the report name to validate
-     * @throws IllegalArgumentException
-     *             if the report name is invalid
-     */
-    private void validateReportName(String reportName) {
-        if (StringUtils.isBlank(reportName)) {
-            throw new IllegalArgumentException("Report name cannot be null or empty");
-        }
-
-        // Basic length validation
-        if (reportName.length() > 100) {
-            throw new IllegalArgumentException("Report name exceeds maximum length of 100 characters");
-        }
-
-        // Check for potentially dangerous characters
-        // Allow letters, numbers, spaces, hyphens, underscores, and parentheses which are common in report names
-        if (!reportName.matches("^[a-zA-Z0-9\\s\\-_()%&.]+$")) {
-            throw new IllegalArgumentException(
-                    "Report name contains invalid characters. Only letters, numbers, spaces, hyphens, underscores, parentheses, percent, ampersand, and dots are allowed");
-        }
-    }
 }

fineract-provider/src/main/java/org/apache/fineract/infrastructure/dataqueries/data/ReportParameters.java

@@ -0,0 +1,173 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.infrastructure.dataqueries.data;
+
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
+
+public final class ReportParameters {
+
+    // Private constructor to prevent instantiation
+    private ReportParameters() {
+        throw new AssertionError("Utility class should not be instantiated");
+    }
+
+    private static final String IS_SELF_SERVICE_USER_REPORT = "isSelfServiceUserReport";
+    private static final String EXPORT_CSV = "exportCSV";
+    private static final String PARAMETER_TYPE = "parameterType";
+    private static final String OUTPUT_TYPE = "output-type";
+    private static final String ENABLE_BUSINESS_DATE = "enable-business-date";
+    private static final String OBLIG_DATE_TYPE = "obligDateType";
+    private static final String DECIMAL_CHOICE = "decimalChoice";
+    private static final String PORTFOLIO_RISK_BRANCH = "Portfolio at Risk by Branch";
+
+    public static final String FULL_DESCRIPTION = "This resource allows you to run and receive output from pre-defined Apache Fineract reports.\n"
+            + "\n" + "Reports can also be used to provide data for searching and workflow functionality.\n" + "\n"
+            + "The default output is a JSON formatted \"Generic Resultset\". The Generic Resultset contains Column Heading as well as Data information. However, you can export to CSV format by simply adding \"&exportCSV=true\" to the end of your URL.\n"
+            + "\n"
+            + "If Pentaho reports have been pre-defined, they can also be run through this resource. Pentaho reports can return HTML, PDF or CSV formats.\n"
+            + "\n"
+            + "The Apache Fineract reference application uses a JQuery plugin called stretchy reporting which, itself, uses this reports resource to provide a pretty flexible reporting User Interface (UI).\n\n"
+            + "\n" + "\n" + "Example Requests:\n" + "\n" + "runreports/Client%20Listing?R_officeId=1\n" + "\n" + "\n"
+            + "runreports/Client%20Listing?R_officeId=1&exportCSV=true\n" + "\n" + "\n"
+            + "runreports/OfficeIdSelectOne?R_officeId=1&parameterType=true\n" + "\n" + "\n"
+            + "runreports/OfficeIdSelectOne?R_officeId=1&parameterType=true&exportCSV=true\n" + "\n" + "\n"
+            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=HTML&R_officeId=1\n"
+            + "\n" + "\n"
+            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=XLS&R_officeId=1\n"
+            + "\n" + "\n"
+            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=CSV&R_officeId=1\n"
+            + "\n" + "\n"
+            + "runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=PDF&R_officeId=1"
+            + "\n\n**Available Parameters (All Optional):**\n\n" + "**Common Control Parameters:**\n"
+            + "- `isSelfServiceUserReport`: Indicates if this is a self-service user report (default: false)\n"
+            + "- `exportCSV`: Set to true to export results as CSV (default: false)\n"
+            + "- `parameterType`: Indicates if this is a parameter type request (default: false)\n"
+            + "- `output-type`: Output format type (HTML, XLS, CSV, PDF)\n" + "- `enable-business-date`: Enable business date filtering\n"
+            + "- `obligDateType`: Obligation date type\n" + "- `decimalChoice`: Decimal formatting choice\n"
+            + "- `Portfolio at Risk by Branch`: Portfolio risk parameter\n\n"
+
+            + "**Common Report Parameters (R_ prefixed):**\n" + "- `R_officeId`: Office ID filter\n"
+            + "- `R_loanOfficerId`: Loan officer ID filter\n" + "- `R_currencyId`: Currency ID filter\n"
+            + "- `R_fromDate`, `R_toDate`: Date range filters (yyyy-MM-dd)\n" + "- `R_accountNo`: Account number filter\n"
+            + "- `R_transactionId`: Transaction ID filter\n" + "- `R_centerId`: Center ID filter\n" + "- `R_branch`: Branch filter\n"
+            + "- `R_ondate`: Specific date filter\n" + "- `R_cycleX`, `R_cycleY`: Cycle filters\n" + "- `R_fromX`, `R_toY`: Range filters\n"
+            + "- `R_overdueX`, `R_overdueY`: Overdue filters\n" + "- `R_endDate`: End date filter\n\n"
+
+            + "**Other Common Parameters:**\n" + "- `OfficeId`: Office ID filter (alternative)\n"
+            + "- `loanOfficerId`: Loan officer ID filter (alternative)\n" + "- `currencyId`: Currency ID filter (alternative)\n"
+            + "- `fundId`: Fund ID filter\n" + "- `loanProductId`: Loan product ID filter\n" + "- `loanPurposeId`: Loan purpose ID filter\n"
+            + "- `parType`: Portfolio at risk type\n" + "- `SelectGLAccountNO`: GL account number selection\n"
+            + "- `SavingsAccountSubStatus`: Savings account status\n" + "- `SelectLoanType`: Loan type selection\n\n"
+
+            + "**Note:** All parameters are optional and report-specific. \n"
+            + "The exact parameters required depend on the specific report being executed.\n"
+            + "Some reports may accept additional parameters not listed here.";
+
+    @Parameters({
+            @Parameter(name = IS_SELF_SERVICE_USER_REPORT, description = "Optional - Indicates if this is a self-service user report", example = "false"),
+            @Parameter(name = EXPORT_CSV, description = "Optional - Set to true to export results as CSV", example = "true"),
+            @Parameter(name = PARAMETER_TYPE, description = "Optional - Indicates if this is a parameter type request", example = "false"),
+            @Parameter(name = OUTPUT_TYPE, description = "Optional - Output format type (HTML, XLS, CSV, PDF)", example = "HTML"),
+            @Parameter(name = ENABLE_BUSINESS_DATE, description = "Optional - Enable business date filtering", example = "true"),
+            @Parameter(name = OBLIG_DATE_TYPE, description = "Optional - Obligation date type", example = "due"),
+            @Parameter(name = DECIMAL_CHOICE, description = "Optional - Decimal formatting choice", example = "2"),
+            @Parameter(name = PORTFOLIO_RISK_BRANCH, description = "Optional - Portfolio at Risk by Branch parameter", example = "30"),
+
+            @Parameter(name = "R_officeId", description = " Office ID filter", example = "1"),
+            @Parameter(name = "R_loanOfficerId", description = "Optional - Loan officer ID filter", example = "5"),
+            @Parameter(name = "R_currencyId", description = "Optional - Currency ID filter", example = "USD"),
+            @Parameter(name = "R_fromDate", description = "Optional - Start date filter (yyyy-MM-dd)", example = "2023-01-01"),
+            @Parameter(name = "R_toDate", description = "Optional - End date filter (yyyy-MM-dd)", example = "2023-12-31"),
+            @Parameter(name = "R_accountNo", description = "Optional - Account number filter", example = "00010001"),
+            @Parameter(name = "R_transactionId", description = "Optional - Transaction ID filter", example = "12345"),
+            @Parameter(name = "R_centerId", description = "Optional - Center ID filter", example = "10"),
+            @Parameter(name = "R_branch", description = "Optional - Branch filter", example = "Main"),
+            @Parameter(name = "R_ondate", description = "Optional - Specific date filter", example = "2023-06-15"),
+            @Parameter(name = "R_cycleX", description = "Optional - Cycle X filter", example = "1"),
+            @Parameter(name = "R_cycleY", description = "Optional - Cycle Y filter", example = "12"),
+            @Parameter(name = "R_fromX", description = "Optional - From X value filter", example = "0"),
+            @Parameter(name = "R_toY", description = "Optional - To Y value filter", example = "100"),
+            @Parameter(name = "R_overdueX", description = "Optional - Overdue X days filter", example = "30"),
+            @Parameter(name = "R_overdueY", description = "Optional - Overdue Y days filter", example = "90"),
+            @Parameter(name = "R_endDate", description = "Optional - End date filter", example = "2023-12-31"),
+
+            @Parameter(name = "OfficeId", description = "Optional - Office ID filter (alternative)", example = "1"),
+            @Parameter(name = "loanOfficerId", description = "Optional - Loan officer ID filter (alternative)", example = "5"),
+            @Parameter(name = "currencyId", description = "Optional - Currency ID filter (alternative)", example = "USD"),
+            @Parameter(name = "fundId", description = "Optional - Fund ID filter", example = "1"),
+            @Parameter(name = "loanProductId", description = "Optional - Loan product ID filter", example = "2"),
+            @Parameter(name = "loanPurposeId", description = "Optional - Loan purpose ID filter", example = "3"),
+            @Parameter(name = "parType", description = "Optional - Portfolio at risk type", example = "30"),
+            @Parameter(name = "SelectGLAccountNO", description = "Optional - GL account number selection", example = "11001"),
+            @Parameter(name = "SavingsAccountSubStatus", description = "Optional - Savings account sub-status", example = "active"),
+            @Parameter(name = "SelectLoanType", description = "Optional - Loan type selection", example = "individual"),
+
+            @Parameter(name = "R_*", description = "Optional - Additional report-specific parameters prefixed with 'R_'") })
+
+    public static void getOpenApiParameters() {
+
+    }
+
+    public static String getIsSelfServiceUserReport() {
+        return IS_SELF_SERVICE_USER_REPORT;
+    }
+
+    public static String getExportCsv() {
+        return EXPORT_CSV;
+    }
+
+    public static String getParameterType() {
+        return PARAMETER_TYPE;
+    }
+
+    public static String getOutputType() {
+        return OUTPUT_TYPE;
+    }
+
+    public static String getEnableBusinessDate() {
+        return ENABLE_BUSINESS_DATE;
+    }
+
+    public static String getObligDateType() {
+        return OBLIG_DATE_TYPE;
+    }
+
+    public static String getDecimalChoice() {
+        return DECIMAL_CHOICE;
+    }
+
+    public static String getPortfolioRiskBranch() {
+        return PORTFOLIO_RISK_BRANCH;
+    }
+
+    public static String getFullDescription() {
+        return FULL_DESCRIPTION;
+    }
+
+    @Parameters({
+            @Parameter(name = IS_SELF_SERVICE_USER_REPORT, description = "Optional - Indicates if this is a self-service user report", example = "false"),
+            @Parameter(name = EXPORT_CSV, description = "Optional - Set to true to export results as CSV", example = "true"),
+            @Parameter(name = PARAMETER_TYPE, description = "Optional - Indicates if this is a parameter type request", example = "false"),
+            @Parameter(name = OUTPUT_TYPE, description = "Optional - Output format type (HTML, XLS, CSV, PDF)", example = "HTML"),
+            @Parameter(name = "R_*", description = "Optional - Report-specific parameters prefixed with 'R_'") })
+    public static void getMinimalOpenApiParameters() {
+
+    }
+}