[Ballerina to OAS] HATEOAS Support

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/ResourceMapperImpl.java

@@ -143,28 +143,28 @@
             }
             case Constants.OPTIONS -> {
                 if (pathObject.containsKey(pathName)) {
                     pathObject.get(pathName).setOptions(operation);
                 } else {
                     pathItem.setOptions(operation);
                     path.addPathItem(pathName, pathItem);
                 }
             }
             case Constants.PATCH -> {
                 if (pathObject.containsKey(pathName)) {
                     pathObject.get(pathName).setPatch(operation);
                 } else {
                     pathItem.setPatch(operation);
                     path.addPathItem(pathName, pathItem);
                 }
             }
             case Constants.HEAD -> {
                 if (pathObject.containsKey(pathName)) {
                     pathObject.get(pathName).setHead(operation);
                 } else {
                     pathItem.setHead(operation);
                     path.addPathItem(pathName, pathItem);
                 }
             }
             default -> { }
         }
     }
@@ -174,26 +174,19 @@
      *
      * @return Operation Adaptor object of given resource
      */
-    private Optional<OperationInventory> convertResourceToOperation(FunctionDefinitionNode resource, String httpMethod,
-                                                                    String generateRelativePath,
+    private Optional<OperationInventory> convertResourceToOperation(FunctionDefinitionNode resourceFunction,
+                                                                    String httpMethod, String generateRelativePath,
                                                                     Components components) {
         OperationInventory operationInventory = new OperationInventory();
         operationInventory.setHttpOperation(httpMethod);
         operationInventory.setPath(generateRelativePath);
-        /* Set operation id */
-        String resName = (resource.functionName().text() + "_" +
-                generateRelativePath).replaceAll("\\{///}", "_");
-
-        if (generateRelativePath.equals("/")) {
-            resName = resource.functionName().text();
-        }
-        operationInventory.setOperationId(getOperationId(resName));
+        operationInventory.setOperationId(getOperationId(resourceFunction));
         // Set operation summary
         // Map API documentation
-        Map<String, String> apiDocs = listAPIDocumentations(resource, operationInventory);
+        Map<String, String> apiDocs = listAPIDocumentations(resourceFunction, operationInventory);
         //Add path parameters if in path and query parameters
-        ParameterMapper parameterMapper = new ParameterMapperImpl(resource, operationInventory, components, apiDocs,
-                additionalData, treatNilableAsOptional);
+        ParameterMapper parameterMapper = new ParameterMapperImpl(resourceFunction, operationInventory, components,
+                apiDocs, additionalData, treatNilableAsOptional);
         parameterMapper.setParameters();
         List<OpenAPIMapperDiagnostic> diagnostics = additionalData.diagnostics();
         if (diagnostics.size() > 1 || (diagnostics.size() == 1 && !diagnostics.get(0).getCode().equals(
@@ -207,7 +200,7 @@
             }
         }
 
-        ResponseMapper responseMapper = new ResponseMapperImpl(resource, operationInventory, components,
+        ResponseMapper responseMapper = new ResponseMapperImpl(resourceFunction, operationInventory, components,
                 additionalData);
         responseMapper.setApiResponses();
         return Optional.of(operationInventory);

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/ServiceToOpenAPIMapper.java

@@ -35,6 +35,9 @@
 import io.ballerina.openapi.service.mapper.diagnostic.DiagnosticMessages;
 import io.ballerina.openapi.service.mapper.diagnostic.ExceptionDiagnostic;
 import io.ballerina.openapi.service.mapper.diagnostic.OpenAPIMapperDiagnostic;
+import io.ballerina.openapi.service.mapper.hateoas.HateoasMapper;
+import io.ballerina.openapi.service.mapper.hateoas.HateoasMapperImpl;
+import io.ballerina.openapi.service.mapper.hateoas.HateoasMetadataVisitor;
 import io.ballerina.openapi.service.mapper.model.AdditionalData;
 import io.ballerina.openapi.service.mapper.model.ModuleMemberVisitor;
 import io.ballerina.openapi.service.mapper.model.OASGenerationMetaInfo;
@@ -62,7 +65,7 @@
  *
  * @since 2.0.0
  */
 public class ServiceToOpenAPIMapper {
 
     /**
      * This method will generate  openapi definition Map lists with ballerina code.
@@ -83,11 +86,11 @@
         List<OpenAPIMapperDiagnostic> diagnostics = new ArrayList<>();
         List<OASResult> outputs = new ArrayList<>();
         if (containErrors(semanticModel.diagnostics())) {
             DiagnosticMessages messages = DiagnosticMessages.OAS_CONVERTOR_106;
             ExceptionDiagnostic error = new ExceptionDiagnostic(messages.getCode(), messages.getDescription(),
                     null);
             diagnostics.add(error);
         } else {
             ModulePartNode modulePartNode = syntaxTree.rootNode();
             extractServiceNodes(serviceName, availableService, servicesToGenerate, modulePartNode, semanticModel);
             // If there are no services found for a given mapper name.
@@ -97,6 +100,8 @@
                         null, serviceName, availableService.toString());
                 diagnostics.add(error);
             }
+            // Extract HATEOAS meta-data for the all the service-declarations in the current project
+            extractHateoasLinkMetadata(project);
             // Generating openapi specification for selected services
             for (Map.Entry<String, ServiceDeclarationNode> serviceNode : servicesToGenerate.entrySet()) {
                 String openApiName = getOpenApiFileName(syntaxTree.filePath(), serviceNode.getKey(), needJson);
@@ -206,12 +211,14 @@
                 ConstraintMapper constraintMapper = new ConstraintMapperImpl(openapi, moduleMemberVisitor,
                         diagnostics);
                 constraintMapper.setConstraints();
+                HateoasMapper hateoasMapper = new HateoasMapperImpl();
+                hateoasMapper.setOpenApiLinks(serviceDefinition, openapi);
                 return new OASResult(openapi, diagnostics);
             } else {
                 return new OASResult(openapi, oasResult.getDiagnostics());
             }
         } else {
             return oasResult;
         }
     }
 
@@ -266,4 +273,17 @@
         }
         return true;
     }
+
+    private static void extractHateoasLinkMetadata(Project project) {
+        String packageId = project.currentPackage().packageId().id().toString();
+        project.currentPackage().moduleIds().forEach(moduleId -> {
+            Module module = project.currentPackage().module(moduleId);
+            SemanticModel semanticModel = project.currentPackage().getCompilation().getSemanticModel(moduleId);
+            HateoasMetadataVisitor hateoasMetadataVisitor = new HateoasMetadataVisitor(packageId, semanticModel);
+            module.documentIds().forEach(documentId -> {
+                SyntaxTree syntaxTreeDoc = module.document(documentId).syntaxTree();
+                syntaxTreeDoc.rootNode().accept(hateoasMetadataVisitor);
+            });
+        });
+    }
 }

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/hateoas/Constants.java

@@ -0,0 +1,7 @@
+package io.ballerina.openapi.service.mapper.hateoas;
+
+public class Constants {
+
+    public static final String OPENAPI_LINK_DEFAULT_REL = "_self";
+    public static final String BALLERINA_LINKEDTO_KEYWORD = "linkedTo";
+}

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/hateoas/HateoasContextHolder.java

@@ -0,0 +1,76 @@
+/*
+ *  Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org) All Rights Reserved.
+ *
+ *  WSO2 LLC. 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 io.ballerina.openapi.service.mapper.hateoas;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * A context-holder to share HATEOAS meta-data information.
+ *
+ * @since 1.9.0
+ */
+public final class HateoasContextHolder {
+    private static HateoasContextHolder instance;
+
+    private final List<Service> hateoasServices;
+
+    public HateoasContextHolder() {
+        this.hateoasServices = new ArrayList<>();
+    }
+
+    public static HateoasContextHolder getHateoasContextHolder() {
+        synchronized (HateoasContextHolder.class) {
+            if (Objects.isNull(instance)) {
+                instance = new HateoasContextHolder();
+            }
+        }
+        return instance;
+    }
+
+    public void updateHateoasResource(String packageId, int serviceId, String resourceName, Resource resource) {
+        Optional<Service> hateoasService = this.hateoasServices.stream()
+                .filter(svc -> packageId.equals(svc.getPackageId()) && svc.getServiceId() == serviceId)
+                .findFirst();
+        if (hateoasService.isEmpty()) {
+            Service service = new Service(packageId, serviceId);
+            service.addResource(resourceName, resource);
+            this.hateoasServices.add(service);
+            return;
+        }
+        Service service = hateoasService.get();
+        service.addResource(resourceName, resource);
+    }
+
+    public Optional<Resource> getHateoasResource(String packageId, int serviceId, String resourceName,
+                                                 String resourceMethod) {
+        return this.hateoasServices.stream()
+                .filter(svc -> svc.getPackageId().equals(packageId) && svc.getServiceId() == serviceId)
+                .findFirst()
+                .flatMap(svc -> svc.getHateoasResourceMapping().entrySet().stream()
+                        .filter(resources -> resourceName.equals(resources.getKey()))
+                        .findFirst()
+                ).flatMap(hateoasResourceMapping -> hateoasResourceMapping.getValue().stream()
+                        .filter(resource -> resourceMethod.equals(resource.resourceMethod()))
+                        .findFirst()
+                );
+    }
+}

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/hateoas/HateoasLink.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2024, WSO2 LLC. (http://www.wso2.com) All Rights Reserved.
+ *
+ * WSO2 LLC. 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 io.ballerina.openapi.service.mapper.hateoas;
+
+public class HateoasLink {
+    private String resourceName;
+    private String relation;
+    private String resourceMethod;
+
+    public String getResourceName() {
+        return resourceName;
+    }
+
+    public void setResourceName(String resourceName) {
+        this.resourceName = resourceName;
+    }
+
+    public String getRel() {
+        return relation;
+    }
+
+    public void setRel(String relation) {
+        this.relation = relation;
+    }
+
+    public String getResourceMethod() {
+        return resourceMethod;
+    }
+
+    public void setResourceMethod(String resourceMethod) {
+        this.resourceMethod = resourceMethod;
+    }
+}

ballerina-to-openapi/src/main/java/io/ballerina/openapi/service/mapper/hateoas/HateoasMapper.java

@@ -0,0 +1,38 @@
+/*
+ *  Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org) All Rights Reserved.
+ *
+ *  WSO2 LLC. 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 io.ballerina.openapi.service.mapper.hateoas;
+
+import io.ballerina.compiler.syntax.tree.ServiceDeclarationNode;
+import io.swagger.v3.oas.models.OpenAPI;
+
+/**
+ * This {@link HateoasMapper} uses to set HATEOAS links into the OpenAPI context.
+ *
+ * @since 1.9.0
+ */
+public interface HateoasMapper {
+
+    /**
+     * Sets HATEOAS links into the OpenAPI context.
+     *
+     * @param serviceNode Specific service declaration node
+     * @param openAPI Current OpenAPI context
+     */
+    void setOpenApiLinks(ServiceDeclarationNode serviceNode, OpenAPI openAPI);
+}