Merge pull request #1736 from lnash94/example_improvements

[master]Add example improvements

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

@@ -354,4 +354,7 @@ public String toString() {
     public static final String EXAMPLES = "examples";
     public static final String OPERATION_ID = "operationId";
     public static final String RESPONSE_ATTRIBUTE = "response";
+    public static final String REQUEST_BODY_ATTRIBUTE = "requestBody";
+    public static final String VALUE = "value";
+    public static final String FILE_PATH = "filePath";
 }

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

@@ -208,7 +208,8 @@ public static OASResult generateOAS(OASGenerationMetaInfo oasGenerationMetaInfo)
                 hateoasMapper.setOpenApiLinks(serviceDefinition, openapi);
 
                 MetaInfoMapper metaInfoMapper = serviceMapperFactory.getMetaInfoMapper();
-                metaInfoMapper.setResourceMetaData(openapi, serviceDefinition);
+                metaInfoMapper.setResourceMetaData(serviceDefinition, openapi, ballerinaFilePath);
+                diagnostics.addAll(metaInfoMapper.getDiagnostics());
 
                 if (openapi.getComponents().getSchemas().isEmpty()) {
                     openapi.setComponents(null);

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

@@ -87,8 +87,15 @@ public enum DiagnosticMessages {
     OAS_CONVERTOR_126("OAS_CONVERTOR_126", "Generated OpenAPI definition does not contain the response" +
             "/request parameter information from the interceptor pipeline. Cause: %s", DiagnosticSeverity.WARNING),
     OAS_CONVERTOR_127("OAS_CONVERTOR_127", "Generated OpenAPI definition does not contain the request" +
-            " parameter information from the interceptor pipeline. Cause: %s", DiagnosticSeverity.WARNING),;
-
+            " parameter information from the interceptor pipeline. Cause: %s", DiagnosticSeverity.WARNING),
+    OAS_CONVERTOR_128("OAS_CONVERTOR_128", "Given example path `%s` is not exist, therefore " +
+            "generated yaml doesn't contain example for `%s` ", DiagnosticSeverity.WARNING),
+    OAS_CONVERTOR_129("OAS_CONVERTOR_129", "Given example path `%s` should be JSON file for" +
+            " example `%s`", DiagnosticSeverity.WARNING),
+    OAS_CONVERTOR_130("OAS_CONVERTOR_130", "Following issue occurred parsing given example:" +
+            " %s", DiagnosticSeverity.WARNING),
+    OAS_CONVERTOR_131("OAS_CONVERTOR_131", "`%s` example can not have a blank path",
+            DiagnosticSeverity.WARNING);
     private final String code;
     private final String description;
     private final DiagnosticSeverity severity;

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

@@ -19,13 +19,19 @@
 package io.ballerina.openapi.service.mapper.metainfo;
 
 import io.ballerina.compiler.syntax.tree.ServiceDeclarationNode;
+import io.ballerina.openapi.service.mapper.diagnostic.OpenAPIMapperDiagnostic;
 import io.swagger.v3.oas.models.OpenAPI;
 
+import java.nio.file.Path;
+import java.util.List;
+
 /**
  * Interface for Meta information mapper.
  *
  * @since 2.0.1
  */
 public interface MetaInfoMapper {
-    void setResourceMetaData(OpenAPI openAPI, ServiceDeclarationNode serviceNode);
+
+    void setResourceMetaData(ServiceDeclarationNode serviceNode, OpenAPI openAPI, Path ballerinaFilePath);
+    List<OpenAPIMapperDiagnostic> getDiagnostics();
 }

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

@@ -36,11 +36,15 @@ public class ResourceMetaInfoAnnotation {
     //<statusCode, <mediaType, <string, Object>>>
     Map<String, Map<String, Map<String, Object>>> responseExamples;
 
+    //<mediaType, <string, Object>>
+    Map<String, Map<String, Object>> requestExamples;
+
     private ResourceMetaInfoAnnotation(Builder builder) {
         this.summary = builder.summary;
         this.operationId = builder.operationId;
         this.tags = builder.tags;
         this.responseExamples = builder.responseExamples;
+        this.requestExamples = builder.requestExamples;
     }
 
     public String getSummary() {
@@ -59,11 +63,16 @@ public Map<String, Map<String, Map<String, Object>>> getResponseExamples() {
         return responseExamples;
     }
 
+    public Map<String, Map<String, Object>>  getRequestExamples() {
+        return requestExamples;
+    }
+
     public static class Builder {
         private String summary;
         private String operationId;
         private List<String> tags = new ArrayList<>();
         private Map<String, Map<String, Map<String, Object>>> responseExamples = new HashMap<>();
+        private Map<String, Map<String, Object>> requestExamples = new HashMap<>();
 
         public Builder summary(String summary) {
             this.summary = summary;
@@ -85,6 +94,11 @@ public Builder responseExamples(Map<String, Map<String, Map<String, Object>>> re
             return this;
         }
 
+        public Builder requestExamples(Map<String, Map<String, Object>> requestExamples) {
+            this.requestExamples = requestExamples;
+            return this;
+        }
+
         public ResourceMetaInfoAnnotation build() {
             return new ResourceMetaInfoAnnotation(this);
         }

gradle.properties

@@ -8,7 +8,7 @@ clientNativeVersion=1.0.1-SNAPSHOT
 clientNativePublish=false
 
 #dependency
-ballerinaLangVersion=2201.9.1
+ballerinaLangVersion=2201.10.0-20240624-004800-68612b63
 testngVersion=7.6.1
 slf4jVersion=1.7.30
 org.gradle.jvmargs=-Xmx4096M -Dfile.encoding=UTF-8

module-ballerina-openapi/annotation.bal

@@ -28,7 +28,7 @@
 # + email - The email address to contact the API provider or support.
 # + contactName - The full name of the person or organization responsible for the API.
 # + contactURL - The URL to a web page with more information about the API, the provider, or support.
-# + termOfService - The URL to the terms of service for the API.
+# + termsOfService - The URL to the terms of service for the API.
 # + licenseName - The name of the license under which the API is provided.
 # + licenseURL - The URL to the full text of the license.
 public type ServiceInformation record {|
@@ -82,14 +82,13 @@ public type ResourceInformation record {|
 #
 # + headers - The headers for the response.
 # + examples - Detailed examples of the response content.
-public type ResponseExample record {
+public type ResponseExample record {|
     map<string> headers?;
-    map<map<record {|record {} value;|}>> examples?;
-
-};
+    map<map<record {|record {} value;|}|record {|string filePath;|}>> examples?;
+|};
 
 # Represents an example of a request body for a specific media type.
-public type RequestExamples map<anydata>;
+public type RequestExamples readonly & map<map<record {|record {} value;|}|record {|string filePath;|}>>;
 
 # Represents examples for resource function.
 #

openapi-validator/src/test/java/io/ballerina/openapi/validator/tests/ReturnTypeValidationTests.java

@@ -214,7 +214,7 @@ public void recordType() {
         DiagnosticResult diagnostic = getCompilation(project);
         Object[] errors = getDiagnostics(diagnostic);
         Assert.assertEquals(errors.length, 1);
-        String typeMismatch = "ERROR [record.bal:(13:5,17:6)] could not find OpenAPI object schema field 'type' in" +
+        String typeMismatch = "ERROR [record.bal:(4:10,7:2)] could not find OpenAPI object schema field 'type' in" +
                 " 'Pet' the Ballerina record.";
         Assert.assertEquals(typeMismatch, errors[0].toString());
     }