Merge pull request ballerina-platform#1831 from ballerina-platform/align-improv

OpenAPI tool enhancements and fixes for connector regeneration

Author: TharmiganK

module-ballerina-openapi/Ballerina.toml

@@ -1,4 +1,4 @@
 [package]
 org= "ballerina"
 name= "openapi"
-version= "@toml.version@"
+version= "2.3.1"

module-ballerina-openapi/CompilerPlugin.toml

@@ -3,7 +3,7 @@ id = "openapi-tools"
 class = "io.ballerina.openapi.validator.OpenAPIValidatorPlugin"
 
 [[dependency]]
-path = "../openapi-validator/build/libs/openapi-validator-@project.version@.jar"
+path = "../openapi-validator/build/libs/openapi-validator-2.3.1-SNAPSHOT.jar"
 groupId = "ballerina"
 artifactId = "openapi"
-version = "@project.version@."
+version = "2.3.1-SNAPSHOT"

openapi-cli/src/main/java/io/ballerina/openapi/cmd/Align.java

@@ -23,6 +23,11 @@
 import picocli.CommandLine;
 
 import java.io.PrintStream;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
 import java.util.Optional;
 
 /**
@@ -38,7 +43,22 @@
 )
 public class Align extends SubCmdBase {
 
+    public static final String INVALID_ALIGNMENT_OPTIONS = "ERROR: Invalid alignment type '%s' provided. " +
+            "The available options are: %s";
     private static final String INFO_MSG_PREFIX = "Aligned";
+    public static final String NAME = "name";
+    public static final String DOC = "doc";
+    public static final String BASEPATH = "basepath";
+    public static final List<String> DEFAULT_ALIGNMENT_TYPES = List.of(NAME, DOC, BASEPATH);
+    private List<String> alignmentTypes = Arrays.asList(NAME, DOC, BASEPATH);
+
+    @CommandLine.Option(names = {"--include"}, description = "Alignment types to be included. " +
+            "The available options are: name, doc, basepath.")
+    public String includedAlignments;
+
+    @CommandLine.Option(names = {"--exclude"}, description = "Alignment types to be excluded. " +
+            "The available options are: name, doc, basepath.")
+    public String excludedAlignments;
 
     public Align() {
         super(CommandType.ALIGN, INFO_MSG_PREFIX);
@@ -48,21 +68,52 @@ public Align(PrintStream errorStream, boolean exitWhenFinish) {
         super(CommandType.ALIGN, INFO_MSG_PREFIX, errorStream, exitWhenFinish);
     }
 
+    @Override
+    public void execute() {
+        setAlignmentTypes();
+        super.execute();
+    }
+
+    private void setAlignmentTypes() {
+        List<String> validatedIncludedAlignments = getValidatedAlignmentTypes(includedAlignments);
+        List<String> validatedExcludedAlignments = getValidatedAlignmentTypes(excludedAlignments);
+        if (!validatedIncludedAlignments.isEmpty()) {
+            alignmentTypes = validatedIncludedAlignments;
+        } else if (!validatedExcludedAlignments.isEmpty()) {
+            alignmentTypes.removeAll(validatedExcludedAlignments);
+        }
+    }
+
+    private List<String> getValidatedAlignmentTypes(String alignmentTypes) {
+        if (Objects.isNull(alignmentTypes) || alignmentTypes.isEmpty()) {
+            return Collections.emptyList();
+        }
+        String[] alignmentTypesList = alignmentTypes.split(COMMA);
+        List<String> validatedAlignmentTypes = new ArrayList<>();
+        for (String alignmentType : alignmentTypesList) {
+            if (DEFAULT_ALIGNMENT_TYPES.contains(alignmentType)) {
+                validatedAlignmentTypes.add(alignmentType);
+            } else {
+                printError(INVALID_ALIGNMENT_OPTIONS.formatted(alignmentType, DEFAULT_ALIGNMENT_TYPES));
+            }
+        }
+        return validatedAlignmentTypes;
+    }
+
     @Override
     public String getDefaultFileName() {
         return "aligned_ballerina_openapi";
     }
 
     @Override
     public Optional<OpenAPI> generate(String openAPIFileContent) {
-        Optional<OpenAPI> filteredOpenAPI = getFilteredOpenAPI(openAPIFileContent, true);
+        Optional<OpenAPI> filteredOpenAPI = getFilteredOpenAPI(openAPIFileContent);
         return filteredOpenAPI.flatMap(this::alignOpenAPI);
     }
 
     private Optional<OpenAPI> alignOpenAPI(OpenAPI openAPI) {
-        OASModifier oasAligner = new OASModifier();
         try {
-            return Optional.of(oasAligner.modifyWithBallerinaConventions(openAPI));
+            return Optional.of(new OASModifier().modify(openAPI, alignmentTypes));
         } catch (BallerinaOpenApiException exp) {
             printError("ERROR: %s".formatted(exp.getMessage()));
             return Optional.empty();

openapi-cli/src/main/java/io/ballerina/openapi/cmd/Flatten.java

@@ -68,7 +68,7 @@ public String getDefaultFileName() {
 
     @Override
     public Optional<OpenAPI> generate(String openAPIFileContent) {
-        Optional<OpenAPI> filteredOpenAPI = getFilteredOpenAPI(openAPIFileContent, false);
+        Optional<OpenAPI> filteredOpenAPI = getFilteredOpenAPI(openAPIFileContent);
         if (filteredOpenAPI.isEmpty()) {
             return Optional.empty();
         }

openapi-cli/src/main/java/io/ballerina/openapi/cmd/SubCmdBase.java

@@ -18,6 +18,7 @@
 package io.ballerina.openapi.cmd;
 
 import io.ballerina.cli.BLauncherCmd;
+import io.ballerina.openapi.core.generators.common.InlineModelResolver;
 import io.ballerina.openapi.core.generators.common.model.Filter;
 import io.ballerina.openapi.service.mapper.utils.CodegenUtils;
 import io.swagger.parser.OpenAPIParser;
@@ -26,7 +27,6 @@
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.parser.core.models.ParseOptions;
 import io.swagger.v3.parser.core.models.SwaggerParseResult;
-import io.swagger.v3.parser.util.InlineModelResolver;
 import picocli.CommandLine;
 
 import java.io.IOException;
@@ -75,7 +75,7 @@ public String getName() {
     }
 
     private static final String COMMAND_IDENTIFIER = "openapi-%s";
-    private static final String COMMA = ",";
+    protected static final String COMMA = ",";
 
     private static final String INFO_OUTPUT_WRITTEN_MSG = "INFO: %s OpenAPI definition file was successfully" +
             " written to: %s%n";
@@ -195,17 +195,16 @@ private void generateOpenAPI() {
     public abstract String getDefaultFileName();
 
     public Optional<OpenAPI> getFlattenOpenAPI(OpenAPI openAPI) {
-        // Flatten the OpenAPI definition with `flattenComposedSchemas: true` and `camelCaseFlattenNaming: true`
-        InlineModelResolver inlineModelResolver = new InlineModelResolver(true, true);
+        // Flatten the OpenAPI definition with `flattenComposedSchemas: true` and `skipMatches: false`
+        InlineModelResolver inlineModelResolver = new InlineModelResolver(true, false);
         inlineModelResolver.flatten(openAPI);
         return Optional.of(openAPI);
     }
 
-    public Optional<OpenAPI> getFilteredOpenAPI(String openAPIFileContent, boolean enableResolver) {
+    public Optional<OpenAPI> getFilteredOpenAPI(String openAPIFileContent) {
         // Read the contents of the file with default parser options
         // Flattening will be done after filtering the operations
         ParseOptions parseOptions = new ParseOptions();
-        parseOptions.setResolve(enableResolver);
         SwaggerParseResult parserResult = new OpenAPIParser().readContents(openAPIFileContent, null,
                 parseOptions);
         if (!parserResult.getMessages().isEmpty() &&

openapi-cli/src/main/resources/cli-help/ballerina-openapi-align.help

@@ -9,12 +9,22 @@ SYNOPSIS
                          [-f | --format] [json|yaml]
                          [-t | --tags] <tag-names>
                          [--operations] <operation-names>
+                         [--include] <align-type-names>
+                         [--exclude] <align-type-names>
+                         [--help]
 
 DESCRIPTION
-       Align the OpenAPI contract file according to the best naming
-       practices of Ballerina. The Ballerina name extensions are added
-       to the schemas which can not be modified directly.
+       Align the OpenAPI contract file according to the best practices of Ballerina.
 
+       By default, the following alignments are done:
+       - `name`: Align according to the best naming practices of Ballerina. The Ballerina
+       name extensions are added to the schemas which can not be modified directly.
+       - `doc`: Align according to the best documentation practices of Ballerina.
+       - `basepath`: Extract the common base path from the operations and add it to the
+       server url.
+
+       The alignments can be filtered using the `--include` and `--exclude` options.
+       The `--include` option has higher priority than the `--exclude` option.
 
 OPTIONS
        -i, --input <openapi-contract-file-path>
@@ -43,6 +53,17 @@ OPTIONS
             This is an optional input. The aligned OpenAPI contract will only
             have the given operations.
 
+       --include <align-type-names>
+            This is an optional input. The aligned OpenAPI contract will only
+            have the given alignments. The supported alignments are: `name`,
+            `doc` and `basepath`.
+
+       --exclude <align-type-names>
+            This is an optional input. The aligned OpenAPI contract will not
+            have the given alignments. The supported alignments are: `name`,
+            `doc`and `basepath`. The `--include` option has higher priority than
+            the `--exclude` option.
+
 EXAMPLES
        Align the `service.yaml` OpenAPI contract file.
            $ bal openapi align -i service.yaml
@@ -54,3 +75,6 @@ EXAMPLES
        Align the `service.json` OpenAPI contract file by filtering the
        operations with the `service` tag.
            $ bal openapi align -i service.json -t service
+
+       Align the `service.json` OpenAPI contract with only the `name` alignment.
+           $ bal openapi align -i service.json --include name

openapi-cli/src/test/java/io/ballerina/openapi/cmd/BallerinaCodeGeneratorLicenseTests.java

@@ -118,7 +118,6 @@ public void testServiceGeneration() throws IOException {
             Assert.fail("Code generation failed. : " + readOutput(true));
         }
     }
-
     @Test(description = "Test openapi to ballerina code generation with default file headers")
     public void testBothClientServiceGeneration() throws IOException {
         Path petstoreYaml = resourceDir.resolve(Paths.get("petstore.yaml"));
@@ -145,6 +144,7 @@ public void testBothClientServiceGeneration() throws IOException {
         }
     }
 
+
     @Test(description = "Test openapi to ballerina code generation with user provided license headers")
     public void testUserGivenLicenseHeader() throws IOException {
         Path petstoreYaml = resourceDir.resolve(Paths.get("petstore.yaml"));

openapi-cli/src/test/java/io/ballerina/openapi/generators/auth/HttpAuthTests.java

@@ -18,9 +18,9 @@
 
 package io.ballerina.openapi.generators.auth;
 
+import io.ballerina.compiler.syntax.tree.AssignmentStatementNode;
 import io.ballerina.compiler.syntax.tree.Node;
 import io.ballerina.compiler.syntax.tree.ParameterNode;
-import io.ballerina.compiler.syntax.tree.VariableDeclarationNode;
 import io.ballerina.openapi.core.generators.client.AuthConfigGeneratorImp;
 import io.ballerina.openapi.core.generators.client.exception.ClientException;
 import io.ballerina.openapi.core.generators.common.GeneratorUtils;
@@ -84,7 +84,7 @@ public void testGetClientInitializationNode() {
         AuthConfigGeneratorImp ballerinaAuthConfigGenerator = new AuthConfigGeneratorImp(
                 false, true);
         String expectedParam = TestConstants.HTTP_CLIENT_DECLARATION;
-        VariableDeclarationNode generatedInitParamNode = ballerinaAuthConfigGenerator.getClientInitializationNode();
+        AssignmentStatementNode generatedInitParamNode = ballerinaAuthConfigGenerator.getClientInitializationNode();
         expectedParam = (expectedParam.trim()).replaceAll("\\s+", "");
         String generatedParamsStr = (generatedInitParamNode.toString().trim()).replaceAll("\\s+", "");
         Assert.assertEquals(expectedParam, generatedParamsStr);

openapi-cli/src/test/java/io/ballerina/openapi/generators/auth/OAuth2Tests.java

@@ -18,10 +18,10 @@
 
 package io.ballerina.openapi.generators.auth;
 
+import io.ballerina.compiler.syntax.tree.AssignmentStatementNode;
 import io.ballerina.compiler.syntax.tree.Node;
 import io.ballerina.compiler.syntax.tree.ParameterNode;
 import io.ballerina.compiler.syntax.tree.TypeDefinitionNode;
-import io.ballerina.compiler.syntax.tree.VariableDeclarationNode;
 import io.ballerina.openapi.core.generators.client.AuthConfigGeneratorImp;
 import io.ballerina.openapi.core.generators.client.exception.ClientException;
 import io.ballerina.openapi.core.generators.common.GeneratorUtils;
@@ -88,7 +88,7 @@ public void testGetClientInitializationNode() {
         AuthConfigGeneratorImp ballerinaAuthConfigGenerator = new AuthConfigGeneratorImp(false,
                 true);
         String expectedParam = TestConstants.HTTP_CLIENT_DECLARATION;
-        VariableDeclarationNode generatedInitParamNode = ballerinaAuthConfigGenerator.getClientInitializationNode();
+        AssignmentStatementNode generatedInitParamNode = ballerinaAuthConfigGenerator.getClientInitializationNode();
         expectedParam = (expectedParam.trim()).replaceAll("\\s+", "");
         String generatedParamsStr = (generatedInitParamNode.toString().trim()).replaceAll("\\s+", "");
         Assert.assertEquals(expectedParam, generatedParamsStr);

openapi-cli/src/test/java/io/ballerina/openapi/generators/client/AllOfResponsesTests.java

@@ -55,7 +55,7 @@ public void getReturnTypeForAllOf() throws IOException, BallerinaOpenApiExceptio
         TypeHandler.createInstance(response, false);
         Operation post = response.getPaths().get("/users/{userId}/meetings").getPost();
         FunctionReturnTypeGeneratorImp functionReturnType = new FunctionReturnTypeGeneratorImp(post, response, "post");
-        assertEquals(functionReturnType.getReturnType().get().type().toString(), "inline_response_201|error");
+        assertEquals(functionReturnType.getReturnType().get().type().toString(), "inline_response_201|error?");
     }
 
     @Test(description = "Tests for the object response without property")