Add API doc while publishing APIs (#79)

Co-authored-by: Sasini_Sandamali <sasini@entgra.io>
Co-authored-by: Pahansith Gunathilake <pahansith@entgra.io>
Reviewed-on: community/device-mgt-core#79
Co-authored-by: Sasini Sandamali <sasini@entgra.io>
Co-committed-by: Sasini Sandamali <sasini@entgra.io>

components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIConfig.java

@@ -28,7 +28,6 @@ import java.util.Set;
 /**
  * This bean class carries the properties used by some API that needs to be published within the underlying
  * API-Management infrastructure.
- *
  * A sample API configuration accepted by this particular bean class would look like what's shown below.
  * e.g.
  *
@@ -47,6 +46,9 @@ public class APIConfig {
     private String name;
     private String owner;
     private String context;
+    private String apiDocumentationName;
+    private String apiDocumentationSummary;
+    private String apiDocumentationSourceFile;
     private String endpoint;
     private String version;
     private String policy;
@@ -82,6 +84,33 @@ public class APIConfig {
         this.name = name;
     }
 
+    @XmlElement(name = "ApiDocumentationName", required = false)
+    public String getApiDocumentationName() {
+        return apiDocumentationName;
+    }
+
+    public void setApiDocumentationName(String apiDocumentationName) {
+        this.apiDocumentationName = apiDocumentationName;
+    }
+
+    @XmlElement(name = "ApiDocumentationSummary", required = false)
+    public String getApiDocumentationSummary() {
+        return apiDocumentationSummary;
+    }
+
+    public void setApiDocumentationSummary(String apiDocumentationSummary) {
+        this.apiDocumentationSummary = apiDocumentationSummary;
+    }
+
+    @XmlElement(name = "ApiDocumentationSourceFile", required = false)
+    public String getApiDocumentationSourceFile() {
+        return apiDocumentationSourceFile;
+    }
+
+    public void setApiDocumentationSourceFile(String apiDocumentationSourceFile) {
+        this.apiDocumentationSourceFile = apiDocumentationSourceFile;
+    }
+
     @XmlElement(name = "Owner", required = true)
     public String getOwner() {
         return owner;

components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIPublisherServiceImpl.java

@@ -21,6 +21,8 @@ package org.wso2.carbon.apimgt.webapp.publisher;
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.wso2.carbon.apimgt.api.model.Documentation;
+import org.wso2.carbon.apimgt.api.model.DocumentationType;
 import org.wso2.carbon.apimgt.api.APIManagementException;
 import org.wso2.carbon.apimgt.api.APIProvider;
 import org.wso2.carbon.apimgt.api.FaultGatewaysException;
@@ -66,18 +68,19 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.Date;
 
 /**
  * This class represents the concrete implementation of the APIPublisherService that corresponds to providing all
  * API publishing related operations.
  */
 public class APIPublisherServiceImpl implements APIPublisherService {
+    public static final APIManagerFactory API_MANAGER_FACTORY = APIManagerFactory.getInstance();
     private static final String UNLIMITED_TIER = "Unlimited";
     private static final String WS_UNLIMITED_TIER = "AsyncUnlimited";
     private static final String API_PUBLISH_ENVIRONMENT = "Default";
     private static final String CREATED_STATUS = "CREATED";
     private static final String PUBLISH_ACTION = "Publish";
-    public static final APIManagerFactory API_MANAGER_FACTORY = APIManagerFactory.getInstance();
     private static final Log log = LogFactory.getLog(APIPublisherServiceImpl.class);
 
     @Override
@@ -293,7 +296,45 @@ public class APIPublisherServiceImpl implements APIPublisherService {
                                 }
                             }
                         }
-                    } catch (FaultGatewaysException | APIManagementException e) {
+                        if (apiConfig.getApiDocumentationSourceFile() != null) {
+                            API api = getAPI(apiConfig, true);
+
+                            String fileName =
+                                    CarbonUtils.getCarbonHome() + File.separator + "repository" +
+                                            File.separator + "resources" + File.separator + "api-docs" + File.separator +
+                                            apiConfig.getApiDocumentationSourceFile();
+
+                            BufferedReader br = new BufferedReader(new FileReader(fileName));
+                            StringBuilder stringBuilder = new StringBuilder();
+                            String line = null;
+                            String ls = System.lineSeparator();
+                            while ((line = br.readLine()) != null) {
+                                stringBuilder.append(line);
+                                stringBuilder.append(ls);
+                            }
+                            stringBuilder.deleteCharAt(stringBuilder.length() - 1);
+                            br.close();
+                            String docContent = stringBuilder.toString();
+
+                            Documentation apiDocumentation = new Documentation(DocumentationType.HOWTO, apiConfig.getApiDocumentationName());
+                            apiDocumentation.setVisibility(Documentation.DocumentVisibility.API_LEVEL);
+                            apiDocumentation.setSourceType(Documentation.DocumentSourceType.MARKDOWN);
+                            apiDocumentation.setCreatedDate(new Date());
+                            apiDocumentation.setLastUpdated(new Date());
+                            apiDocumentation.setSummary(apiConfig.getApiDocumentationSummary());
+                            apiDocumentation.setOtherTypeName(null);
+
+                            try {
+                                //Including below code lines inside the try block because  'getDocumentation' method returns an APIManagementException exception when it doesn't have any existing doc
+                                Documentation existingDoc = apiProvider.getDocumentation(api.getId(), DocumentationType.HOWTO, apiConfig.getApiDocumentationName());
+                                apiProvider.removeDocumentation(api.getId(), existingDoc.getId(), null);
+                            } catch (APIManagementException e) {
+                                log.info("There is no any existing api documentation.");
+                            }
+                            apiProvider.addDocumentation(api.getId(), apiDocumentation);
+                            apiProvider.addDocumentationContent(api, apiConfig.getApiDocumentationName(), docContent);
+                        }
+                    } catch (FaultGatewaysException | APIManagementException | IOException e) {
                         String msg = "Error occurred while publishing api";
                         log.error(msg, e);
                         throw new APIManagerPublisherException(e);

components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIPublisherUtil.java

@@ -104,7 +104,32 @@ public class APIPublisherUtil {
         }
         apiConfig.setVersion(version);
 
+        String apiDocumentationName = apiDef.getApiDocumentationName();
+        if (apiDocumentationName == null || apiDocumentationName.isEmpty()) {
+            if (log.isDebugEnabled()) {
+                log.debug("'API Documentation not set in @SwaggerDefinition Annotation'");
+            }
+        } else {
+            apiConfig.setApiDocumentationName(apiDef.getApiDocumentationName());
+        }
 
+        String apiDocumentationSummary = apiDef.getApiDocumentationSummary();
+        if (apiDocumentationSummary == null || apiDocumentationSummary.isEmpty()) {
+            if (log.isDebugEnabled()) {
+                log.debug("'API Documentation summary not set in @SwaggerDefinition Annotation'");
+            }
+        } else {
+            apiConfig.setApiDocumentationSummary(apiDef.getApiDocumentationSummary());
+        }
+
+        String apiDocumentationSourceFile = apiDef.getApiDocumentationSourceFile();
+        if (apiDocumentationSourceFile == null || apiDocumentationSourceFile.isEmpty()) {
+            if (log.isDebugEnabled()) {
+                log.debug("'API Documentation source file not set in @SwaggerDefinition Annotation'");
+            }
+        } else {
+            apiConfig.setApiDocumentationSourceFile(apiDef.getApiDocumentationSourceFile());
+        }
         String context = apiDef.getContext();
         if (context == null || context.isEmpty()) {
             if (log.isDebugEnabled()) {

components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/config/APIResourceConfiguration.java

@@ -27,6 +27,9 @@ public class APIResourceConfiguration {
 
     private String name;
     private String context;
+    private String apiDocumentationName;
+    private String apiDocumentationSummary;
+    private String apiDocumentationSourceFile;
     private String version;
     private List<APIResource> resources;
     private String[] tags;
@@ -62,6 +65,35 @@ public class APIResourceConfiguration {
         this.name = name;
     }
 
+    public String getApiDocumentationName() {
+        return apiDocumentationName;
+    }
+
+    @XmlElement(name = "ApiDocumentation")
+
+
+    public void setApiDocumentationName(String apiDocumentationName) {
+        this.apiDocumentationName = apiDocumentationName;
+    }
+
+    public String getApiDocumentationSummary() {
+        return apiDocumentationSummary;
+    }
+
+    @XmlElement(name = "ApiDocumentationSummary")
+    public void setApiDocumentationSummary(String apiDocumentationSummary) {
+        this.apiDocumentationSummary = apiDocumentationSummary;
+    }
+
+    public String getApiDocumentationSourceFile() {
+        return apiDocumentationSourceFile;
+    }
+
+    @XmlElement(name = "ApiDocumentationSourceFile")
+    public void setApiDocumentationSourceFile(String apiDocumentationSourceFile) {
+        this.apiDocumentationSourceFile = apiDocumentationSourceFile;
+    }
+
     public String getVersion() {
         return version;
     }
@@ -110,6 +142,7 @@ public class APIResourceConfiguration {
     public String getAsyncApiDefinition() {
         return asyncApiDefinition;
     }
+
     @XmlElement(name = "asyncApiDefinition")
     public void setAsyncApiDefinition(String asyncApiDefinition) {
         this.asyncApiDefinition = asyncApiDefinition;

components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/lifecycle/util/AnnotationProcessor.java

@@ -53,7 +53,6 @@ import java.util.*;
 public class AnnotationProcessor {
 
     private static final Log log = LogFactory.getLog(AnnotationProcessor.class);
-
     private static final String AUTH_TYPE = "Application & Application User";
     private static final String STRING_ARR = "string_arr";
     private static final String STRING = "string";
@@ -61,7 +60,6 @@ public class AnnotationProcessor {
     private static final String PACKAGE_ORG_CODEHAUS = "org.codehaus";
     private static final String PACKAGE_ORG_SPRINGFRAMEWORK = "org.springframework";
     public static final String WILD_CARD = "/*";
-
     private static final String SWAGGER_ANNOTATIONS_INFO = "info";
     private static final String SWAGGER_ANNOTATIONS_TAGS = "tags";
     private static final String SWAGGER_ANNOTATIONS_EXTENSIONS = "extensions";
@@ -73,6 +71,9 @@ public class AnnotationProcessor {
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_ROLES = "roles";
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_VERSION = "version";
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_CONTEXT = "context";
+    private static final String SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_NAME = "apiDocumentationName";
+    private static final String SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_SUMMARY = "apiDocumentationSummary";
+    private static final String SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_SOURCE_FILE = "apiDocumentationSourceFile";
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_ENDPOINT_TYPE = "endpointType";
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_NAME = "inSequenceName";
     private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_CONFIG = "inSequenceConfig";
@@ -131,7 +132,6 @@ public class AnnotationProcessor {
             log.error("An error has occurred while loading classes ", e);
         }
     }
-
     public Set<String> scanStandardContext(String className) throws IOException {
         ExtendedAnnotationDB db = new ExtendedAnnotationDB();
         db.addIgnoredPackages(PACKAGE_ORG_APACHE);
@@ -369,7 +369,7 @@ public class AnnotationProcessor {
      * Iterate API annotation and build API Configuration
      *
      * @param annotation reading @SwaggerDefinition annotation
-     * @return APIResourceConfiguration which compose with an API information which has its name, context,version,and tags
+     * @return APIResourceConfiguration which compose with an API information which has its name, context, version, api-documentation, and tags
      * @throws Throwable
      */
     private APIResourceConfiguration processAPIAnnotation(Annotation annotation) throws Throwable {
@@ -411,6 +411,18 @@ public class AnnotationProcessor {
                     if ("".equals(value)) return null;
                     apiResourceConfig.setContext(value);
                     break;
+                case SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_NAME:
+                    if ("".equals(value)) return null;
+                    apiResourceConfig.setApiDocumentationName(value);
+                    break;
+                case SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_SUMMARY:
+                    if ("".equals(value)) return null;
+                    apiResourceConfig.setApiDocumentationSummary(value);
+                    break;
+                case SWAGGER_ANNOTATIONS_PROPERTIES_API_DOCUMENTATION_SOURCE_FILE:
+                    if ("".equals(value)) return null;
+                    apiResourceConfig.setApiDocumentationSourceFile(value);
+                    break;
                 case SWAGGER_ANNOTATIONS_PROPERTIES_ENDPOINT_TYPE:
                     if ("".equals(value))
                         return null;
@@ -485,19 +497,15 @@ public class AnnotationProcessor {
      * @param servletContext
      * @return null if cannot determin /WEB-INF/classes
      */
-    private static URL findWebInfClassesPath(ServletContext servletContext)
-    {
+    private static URL findWebInfClassesPath(ServletContext servletContext) {
         String path = servletContext.getRealPath("/WEB-INF/classes");
         if (path == null) return null;
         File fp = new File(path);
         if (fp.exists() == false) return null;
-        try
-        {
+        try {
             URI uri = fp.toURI();
             return uri.toURL();
-        }
-        catch (MalformedURLException e)
-        {
+        } catch (MalformedURLException e) {
             throw new RuntimeException(e);
         }
     }