community
/
device-mgt-core
12
0
Fork 47
Code Issues Pull Requests 15 Packages Projects Releases Wiki Activity
Labels Milestones
New Pull Request

Add API doc while publishing APIs #79

Merged
pahansith merged 4 commits from :doc-publish into master 2 years ago
Conversation 1 Commits 4 Files Changed 5
5 changed files with 239 additions and 103 deletions
Show Stats Download Patch File Download Diff File

31
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,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;

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.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);

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

@ -64,7 +64,7 @@ public class APIPublisherUtil {
}
public static String getWsServerBaseUrl() {
return getServerBaseUrl().replace("https","wss");
return getServerBaseUrl().replace("https", "wss");
}
public static String getApiEndpointUrl(String context) {
@ -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()) {
@ -302,20 +327,20 @@ public class APIPublisherUtil {
public static void setResourceAuthTypes(ServletContext servletContext, APIConfig apiConfig) {
List<String> resourcesList = null;
String nonSecuredResources = servletContext.getInitParameter(NON_SECURED_RESOURCES);
if(null != nonSecuredResources){
if (null != nonSecuredResources) {
resourcesList = Arrays.asList(nonSecuredResources.split(","));
}
Set<ApiUriTemplate> templates = apiConfig.getUriTemplates();
if(null != resourcesList) {
if (null != resourcesList) {
for (ApiUriTemplate template : templates) {
String fullPaath = "";
if (!template.getUriTemplate().equals(AnnotationProcessor.WILD_CARD)) {
fullPaath = apiConfig.getContext() + template.getUriTemplate();
}
else{
else {
fullPaath = apiConfig.getContext();
}
for(String context : resourcesList) {
for (String context : resourcesList) {
if (context.trim().equals(fullPaath)) {
template.setAuthType(AUTH_TYPE_NON_SECURED);
}

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 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;

88
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

@ -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";
@ -112,26 +113,25 @@ public class AnnotationProcessor {
pathClazz = (Class<Path>) classLoader.loadClass(Path.class.getName());
consumesClass = (Class<Consumes>) classLoader.loadClass(Consumes.class.getName());
producesClass = (Class<Produces>) classLoader.loadClass(Produces.class.getName());
apiClazz= (Class<SwaggerDefinition>)classLoader.loadClass((SwaggerDefinition.class.getName()));
infoClass = (Class<io.swagger.annotations.Info>)classLoader
apiClazz = (Class<SwaggerDefinition>) classLoader.loadClass((SwaggerDefinition.class.getName()));
infoClass = (Class<io.swagger.annotations.Info>) classLoader
.loadClass((io.swagger.annotations.Info.class.getName()));
tagClass = (Class<io.swagger.annotations.Tag>)classLoader
tagClass = (Class<io.swagger.annotations.Tag>) classLoader
.loadClass((io.swagger.annotations.Tag.class.getName()));
extensionClass = (Class<io.swagger.annotations.Extension>)classLoader
extensionClass = (Class<io.swagger.annotations.Extension>) classLoader
.loadClass((io.swagger.annotations.Extension.class.getName()));
extensionPropertyClass = (Class<io.swagger.annotations.ExtensionProperty>)classLoader
extensionPropertyClass = (Class<io.swagger.annotations.ExtensionProperty>) classLoader
.loadClass(io.swagger.annotations.ExtensionProperty.class.getName());
scopeClass = (Class<org.wso2.carbon.apimgt.annotations.api.Scope>) classLoader
.loadClass(org.wso2.carbon.apimgt.annotations.api.Scope.class.getName());
scopesClass = (Class<org.wso2.carbon.apimgt.annotations.api.Scopes>) classLoader
.loadClass(org.wso2.carbon.apimgt.annotations.api.Scopes.class.getName());
apiOperation = (Class<ApiOperation>)classLoader
apiOperation = (Class<ApiOperation>) classLoader
.loadClass((ApiOperation.class.getName()));
} catch (ClassNotFoundException e) {
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);
@ -166,7 +166,7 @@ public class AnnotationProcessor {
if (Scopes != null) {
apiScopes = processAPIScopes(Scopes);
}
if(apiResourceConfig != null){
if (apiResourceConfig != null) {
String rootContext = servletContext.getContextPath();
pathClazzMethods = pathClazz.getMethods();
Annotation rootContectAnno = clazz.getAnnotation(pathClazz);
@ -199,21 +199,21 @@ public class AnnotationProcessor {
" This API will not be published.";
log.error(msg, e1);
} catch (RuntimeException e) {
log.error("Unexpected error has been occurred while publishing "+ className
+"hence, this API will not be published.");
log.error("Unexpected error has been occurred while publishing " + className
+ "hence, this API will not be published.");
throw new RuntimeException(e);
}
return apiResourceConfig;
}
});
if(apiResourceConfiguration !=null)
if (apiResourceConfiguration != null)
apiResourceConfigs.add(apiResourceConfiguration);
}
}
return apiResourceConfigs;
}
private Map<String,ApiScope> processAPIScopes(Annotation annotation) throws Throwable {
private Map<String, ApiScope> processAPIScopes(Annotation annotation) throws Throwable {
Map<String, ApiScope> scopes = new HashMap<>();
InvocationHandler methodHandler = Proxy.getInvocationHandler(annotation);
@ -225,7 +225,7 @@ public class AnnotationProcessor {
StringBuilder aggregatedPermissions;
String roles[];
StringBuilder aggregatedRoles;
for(int i=0; i<annotatedScopes.length; i++){
for (int i = 0; i < annotatedScopes.length; i++) {
aggregatedPermissions = new StringBuilder();
aggregatedRoles = new StringBuilder();
methodHandler = Proxy.getInvocationHandler(annotatedScopes[i]);
@ -236,16 +236,16 @@ public class AnnotationProcessor {
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_DESCRIPTION), annotatedScopes[i], STRING));
scope.setKey(invokeMethod(scopeClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_KEY), annotatedScopes[i], STRING));
permissions = (String[])methodHandler.invoke(annotatedScopes[i], scopeClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_PERMISSIONS, null),null);
permissions = (String[]) methodHandler.invoke(annotatedScopes[i], scopeClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_PERMISSIONS, null), null);
for (String permission : permissions) {
aggregatedPermissions.append(PERMISSION_PREFIX);
aggregatedPermissions.append(permission);
aggregatedPermissions.append(" ");
}
scope.setPermissions(aggregatedPermissions.toString().trim());
roles = (String[])methodHandler.invoke(annotatedScopes[i], scopeClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_ROLES, null),null);
roles = (String[]) methodHandler.invoke(annotatedScopes[i], scopeClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_ROLES, null), null);
for (String role : roles) {
aggregatedRoles.append(role);
aggregatedRoles.append(",");
@ -369,30 +369,30 @@ 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 {
InvocationHandler methodHandler = Proxy.getInvocationHandler(annotation);
Annotation info = (Annotation) methodHandler.invoke(annotation, apiClazz
.getMethod(SWAGGER_ANNOTATIONS_INFO,null),null);
.getMethod(SWAGGER_ANNOTATIONS_INFO, null), null);
Annotation[] tags = (Annotation[]) methodHandler.invoke(annotation, apiClazz
.getMethod(SWAGGER_ANNOTATIONS_TAGS,null),null);
.getMethod(SWAGGER_ANNOTATIONS_TAGS, null), null);
String[] tagNames = new String[tags.length];
for(int i=0; i<tags.length; i++){
for (int i = 0; i < tags.length; i++) {
methodHandler = Proxy.getInvocationHandler(tags[i]);
tagNames[i]=(String)methodHandler.invoke(tags[i], tagClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_NAME, null),null);
tagNames[i] = (String) methodHandler.invoke(tags[i], tagClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_NAME, null), null);
}
methodHandler = Proxy.getInvocationHandler(info);
String version = (String)methodHandler.invoke(info, infoClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_VERSION,null),null);
if("".equals(version))return null;
Annotation[] apiInfo = (Annotation[])methodHandler.invoke(info, infoClass
.getMethod(SWAGGER_ANNOTATIONS_EXTENSIONS,null),null);
String version = (String) methodHandler.invoke(info, infoClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_VERSION, null), null);
if ("".equals(version)) return null;
Annotation[] apiInfo = (Annotation[]) methodHandler.invoke(info, infoClass
.getMethod(SWAGGER_ANNOTATIONS_EXTENSIONS, null), null);
methodHandler = Proxy.getInvocationHandler(apiInfo[0]);
Annotation[] properties = (Annotation[])methodHandler.invoke(apiInfo[0], extensionClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES,null), null);
Annotation[] properties = (Annotation[]) methodHandler.invoke(apiInfo[0], extensionClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES, null), null);
APIResourceConfiguration apiResourceConfig = new APIResourceConfiguration();
for (Annotation property : properties) {
methodHandler = Proxy.getInvocationHandler(property);
@ -400,7 +400,7 @@ public class AnnotationProcessor {
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_NAME, null),
null);
String value = (String) methodHandler.invoke(property, extensionPropertyClass
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_VALUE, null),null);
.getMethod(SWAGGER_ANNOTATIONS_PROPERTIES_VALUE, null), null);
if ("".equals(key)) return null;
switch (key) {
case SWAGGER_ANNOTATIONS_PROPERTIES_NAME:
@ -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);
}
}

Write Preview
Loading…
Cancel
Save