community
/
device-mgt-core
12
0
Fork 46
Code Issues Pull Requests 24 Packages Projects Releases Wiki Activity

Add api-doc while publishing APIs

Browse Source
pull/79/head
Sasini Sandamali 2 years ago
parent 0009bdd460
commit 1864d659e1
5 changed files with 258 additions and 121 deletions
Show Stats Download Patch File Download Diff File

32
components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIConfig.java
Unescape View File

@ -28,7 +28,7 @@ import java.util.Set;
/** /**
* This bean class carries the properties used by some API that needs to be published within the underlying * This bean class carries the properties used by some API that needs to be published within the underlying
* API-Management infrastructure. * API-Management infrastructure.
* * <p>
* A sample API configuration accepted by this particular bean class would look like what's shown below. * A sample API configuration accepted by this particular bean class would look like what's shown below.
* e.g. * e.g.
* *
@ -47,6 +47,9 @@ public class APIConfig {
private String name; private String name;
private String owner; private String owner;
private String context; private String context;
private String apiDocumentationName;
private String apiDocumentationSummary;
private String apiDocumentationSourceFile;
private String endpoint; private String endpoint;
private String version; private String version;
private String policy; private String policy;
@ -82,6 +85,33 @@ public class APIConfig {
this.name = name; 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) @XmlElement(name = "Owner", required = true)
public String getOwner() { public String getOwner() {
return owner; return owner;

45
components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIPublisherServiceImpl.java
Unescape View File

@ -21,6 +21,8 @@ package org.wso2.carbon.apimgt.webapp.publisher;
import org.apache.commons.lang.StringUtils; import org.apache.commons.lang.StringUtils;
import org.apache.commons.logging.Log; import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory; 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.APIManagementException;
import org.wso2.carbon.apimgt.api.APIProvider; import org.wso2.carbon.apimgt.api.APIProvider;
import org.wso2.carbon.apimgt.api.FaultGatewaysException; import org.wso2.carbon.apimgt.api.FaultGatewaysException;
@ -66,18 +68,19 @@ import java.util.Iterator;
import java.util.List; import java.util.List;
import java.util.Map; import java.util.Map;
import java.util.Set; import java.util.Set;
import java.util.Date;
/** /**
* This class represents the concrete implementation of the APIPublisherService that corresponds to providing all * This class represents the concrete implementation of the APIPublisherService that corresponds to providing all
* API publishing related operations. * API publishing related operations.
*/ */
public class APIPublisherServiceImpl implements APIPublisherService { 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 UNLIMITED_TIER = "Unlimited";
private static final String WS_UNLIMITED_TIER = "AsyncUnlimited"; private static final String WS_UNLIMITED_TIER = "AsyncUnlimited";
private static final String API_PUBLISH_ENVIRONMENT = "Default"; private static final String API_PUBLISH_ENVIRONMENT = "Default";
private static final String CREATED_STATUS = "CREATED"; private static final String CREATED_STATUS = "CREATED";
private static final String PUBLISH_ACTION = "Publish"; 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); private static final Log log = LogFactory.getLog(APIPublisherServiceImpl.class);
@Override @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"; String msg = "Error occurred while publishing api";
log.error(msg, e); log.error(msg, e);
throw new APIManagerPublisherException(e); throw new APIManagerPublisherException(e);

28
components/apimgt-extensions/org.wso2.carbon.apimgt.webapp.publisher/src/main/java/org/wso2/carbon/apimgt/webapp/publisher/APIPublisherUtil.java
Unescape View File

@ -104,7 +104,32 @@ public class APIPublisherUtil {
} }
apiConfig.setVersion(version); 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(); String context = apiDef.getContext();
if (context == null || context.isEmpty()) { if (context == null || context.isEmpty()) {
if (log.isDebugEnabled()) { if (log.isDebugEnabled()) {
@ -311,8 +336,7 @@ public class APIPublisherUtil {
String fullPaath = ""; String fullPaath = "";
if (!template.getUriTemplate().equals(AnnotationProcessor.WILD_CARD)) { if (!template.getUriTemplate().equals(AnnotationProcessor.WILD_CARD)) {
fullPaath = apiConfig.getContext() + template.getUriTemplate(); fullPaath = apiConfig.getContext() + template.getUriTemplate();
} } else {
else{
fullPaath = apiConfig.getContext(); fullPaath = apiConfig.getContext();
} }
for (String context : resourcesList) { for (String context : resourcesList) {

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

@ -27,6 +27,9 @@ public class APIResourceConfiguration {
private String name; private String name;
private String context; private String context;
private String apiDocumentationName;
private String apiDocumentationSummary;
private String apiDocumentationSourceFile;
private String version; private String version;
private List<APIResource> resources; private List<APIResource> resources;
private String[] tags; private String[] tags;
@ -62,6 +65,35 @@ public class APIResourceConfiguration {
this.name = name; 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() { public String getVersion() {
return version; return version;
} }
@ -110,6 +142,7 @@ public class APIResourceConfiguration {
public String getAsyncApiDefinition() { public String getAsyncApiDefinition() {
return asyncApiDefinition; return asyncApiDefinition;
} }
@XmlElement(name = "asyncApiDefinition") @XmlElement(name = "asyncApiDefinition")
public void setAsyncApiDefinition(String asyncApiDefinition) { public void setAsyncApiDefinition(String asyncApiDefinition) {
this.asyncApiDefinition = asyncApiDefinition; this.asyncApiDefinition = asyncApiDefinition;

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

@ -52,16 +52,14 @@ import java.util.*;
public class AnnotationProcessor { public class AnnotationProcessor {
public static final String WILD_CARD = "/*";
private static final Log log = LogFactory.getLog(AnnotationProcessor.class); private static final Log log = LogFactory.getLog(AnnotationProcessor.class);
private static final String AUTH_TYPE = "Application & Application User"; private static final String AUTH_TYPE = "Application & Application User";
private static final String STRING_ARR = "string_arr"; private static final String STRING_ARR = "string_arr";
private static final String STRING = "string"; private static final String STRING = "string";
private static final String PACKAGE_ORG_APACHE = "org.apache"; private static final String PACKAGE_ORG_APACHE = "org.apache";
private static final String PACKAGE_ORG_CODEHAUS = "org.codehaus"; private static final String PACKAGE_ORG_CODEHAUS = "org.codehaus";
private static final String PACKAGE_ORG_SPRINGFRAMEWORK = "org.springframework"; 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_INFO = "info";
private static final String SWAGGER_ANNOTATIONS_TAGS = "tags"; private static final String SWAGGER_ANNOTATIONS_TAGS = "tags";
private static final String SWAGGER_ANNOTATIONS_EXTENSIONS = "extensions"; 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_ROLES = "roles";
private static final String SWAGGER_ANNOTATIONS_PROPERTIES_VERSION = "version"; 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_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_ENDPOINT_TYPE = "endpointType";
private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_NAME = "inSequenceName"; private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_NAME = "inSequenceName";
private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_CONFIG = "inSequenceConfig"; private static final String SWAGGER_ANNOTATIONS_PROPERTIES_IN_SEQUENCE_CONFIG = "inSequenceConfig";
@ -132,6 +133,26 @@ public class AnnotationProcessor {
} }
} }
/**
* Find the URL pointing to "/WEB-INF/classes" This method may not work in conjunction with IteratorFactory
* if your servlet container does not extract the /WEB-INF/classes into a real file-based directory
*
* @param servletContext
* @return null if cannot determin /WEB-INF/classes
*/
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 {
URI uri = fp.toURI();
return uri.toURL();
} catch (MalformedURLException e) {
throw new RuntimeException(e);
}
}
public Set<String> scanStandardContext(String className) throws IOException { public Set<String> scanStandardContext(String className) throws IOException {
ExtendedAnnotationDB db = new ExtendedAnnotationDB(); ExtendedAnnotationDB db = new ExtendedAnnotationDB();
db.addIgnoredPackages(PACKAGE_ORG_APACHE); db.addIgnoredPackages(PACKAGE_ORG_APACHE);
@ -369,7 +390,7 @@ public class AnnotationProcessor {
* Iterate API annotation and build API Configuration * Iterate API annotation and build API Configuration
* *
* @param annotation reading @SwaggerDefinition annotation * @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 * @throws Throwable
*/ */
private APIResourceConfiguration processAPIAnnotation(Annotation annotation) throws Throwable { private APIResourceConfiguration processAPIAnnotation(Annotation annotation) throws Throwable {
@ -411,6 +432,18 @@ public class AnnotationProcessor {
if ("".equals(value)) return null; if ("".equals(value)) return null;
apiResourceConfig.setContext(value); apiResourceConfig.setContext(value);
break; 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: case SWAGGER_ANNOTATIONS_PROPERTIES_ENDPOINT_TYPE:
if ("".equals(value)) if ("".equals(value))
return null; return null;
@ -478,30 +511,6 @@ public class AnnotationProcessor {
} }
} }
/**
* Find the URL pointing to "/WEB-INF/classes" This method may not work in conjunction with IteratorFactory
* if your servlet container does not extract the /WEB-INF/classes into a real file-based directory
*
* @param servletContext
* @return null if cannot determin /WEB-INF/classes
*/
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
{
URI uri = fp.toURI();
return uri.toURL();
}
catch (MalformedURLException e)
{
throw new RuntimeException(e);
}
}
private APIResource getAPiOperationExtensions(Annotation currentMethod, APIResource apiResource) throws Throwable { private APIResource getAPiOperationExtensions(Annotation currentMethod, APIResource apiResource) throws Throwable {
InvocationHandler methodHandler = Proxy.getInvocationHandler(currentMethod); InvocationHandler methodHandler = Proxy.getInvocationHandler(currentMethod);
Annotation[] extensions = (Annotation[]) methodHandler.invoke(currentMethod, Annotation[] extensions = (Annotation[]) methodHandler.invoke(currentMethod,

Write Preview
Loading…
Cancel
Save