Examples with Javadoc org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.Javadoc used on opensource projects

Example 1 with Javadoc

use of org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.Javadoc in project herd by FINRAOS.

the class RestControllerProcessor method processJavaDocTag.

/**
 * Processes the Java doc tag (i.e. the parameters and return value).
 *
 * @param javaDocTag the Java doc tag
 * @param methodParamDescriptions the map of method parameters to update.
 */
private void processJavaDocTag(JavaDocTag javaDocTag, Map<String, String> methodParamDescriptions) {
    // Get the list of fragments which are the parts of an individual Javadoc parameter or return value.
    TagElement tagElement = (TagElement) javaDocTag.getInternal();
    List fragments = tagElement.fragments();
    // We need to populate the parameter name and get the list of fragments that contain the actual text.
    String paramName = "";
    List subFragments = new ArrayList<>();
    if (javaDocTag.getName().equals("@param")) {
        // In the case of @param, the first fragment is the name and the rest make up the description.
        paramName = String.valueOf(fragments.get(0));
        subFragments = fragments.subList(1, fragments.size());
    } else if (javaDocTag.getName().equals("@return")) {
        // In the case of @return, we'll use "@return" itself for the name and all the fragments make up the description.
        paramName = "@return";
        subFragments = fragments;
    }
    // Process all fragments and place the results in the map.
    StringBuilder stringBuilder = new StringBuilder();
    processFragments(subFragments, stringBuilder);
    methodParamDescriptions.put(paramName, stringBuilder.toString());
}

Example 2 with Javadoc

use of org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.Javadoc in project herd by FINRAOS.

the class RestControllerProcessor method processRestControllerMethod.

/**
 * Processes a method in a REST controller which represents an endpoint, that is, it is annotated with RequestMapping.
 *
 * @param method the method.
 * @param classRequestMapping the parent.
 * @param tagName the tag name.
 * @param methodSource the method source information.
 *
 * @throws MojoExecutionException if any errors were encountered.
 */
// CollectionUtils doesn't work with generics.
@SuppressWarnings("unchecked")
private void processRestControllerMethod(Method method, RequestMapping classRequestMapping, String tagName, MethodSource<JavaClassSource> methodSource) throws MojoExecutionException {
    log.debug("Processing method \"" + method.getName() + "\".");
    // Build a map of each parameter name to its description from the method Javadoc (i.e. all @param and @return values).
    Map<String, String> methodParamDescriptions = new HashMap<>();
    JavaDocSource<MethodSource<JavaClassSource>> javaDocSource = methodSource.getJavaDoc();
    List<JavaDocTag> tags = javaDocSource.getTags();
    for (JavaDocTag javaDocTag : tags) {
        processJavaDocTag(javaDocTag, methodParamDescriptions);
    }
    List<String> produces = Collections.emptyList();
    List<String> consumes = Collections.emptyList();
    List<RequestMethod> requestMethods = Collections.emptyList();
    List<String> uris = Collections.emptyList();
    // If a class request mapping exists, use it as the default.
    if (classRequestMapping != null) {
        produces = CollectionUtils.arrayToList(classRequestMapping.produces());
        consumes = CollectionUtils.arrayToList(classRequestMapping.consumes());
        requestMethods = CollectionUtils.arrayToList(classRequestMapping.method());
        uris = CollectionUtils.arrayToList(classRequestMapping.value());
    }
    // Get the API Operation and see if this endpoint is hidden.
    ApiOperation apiOperation = method.getAnnotation(ApiOperation.class);
    boolean hidden = apiOperation != null && apiOperation.hidden();
    // Only process methods that have a RequestMapping annotation.
    RequestMapping methodRequestMapping = method.getAnnotation(RequestMapping.class);
    if ((methodRequestMapping != null) && (!hidden)) {
        log.debug("Method \"" + method.getName() + "\" is a RequestMapping.");
        // Override values with method level ones if present.
        requestMethods = getClassOrMethodValue(requestMethods, CollectionUtils.arrayToList(methodRequestMapping.method()));
        uris = getClassOrMethodValue(uris, CollectionUtils.arrayToList(methodRequestMapping.value()));
        produces = getClassOrMethodValue(produces, CollectionUtils.arrayToList(methodRequestMapping.produces()));
        consumes = getClassOrMethodValue(consumes, CollectionUtils.arrayToList(methodRequestMapping.consumes()));
        // Perform validation.
        if (requestMethods.isEmpty()) {
            log.warn("No request method defined for method \"" + method.getName() + "\". Skipping...");
            return;
        }
        if (uris.isEmpty()) {
            log.warn("No URI defined for method \"" + method.getName() + "\". Skipping...");
            return;
        }
        if (uris.size() > 1) {
            log.warn(uris.size() + " URI's found for method \"" + method.getName() + "\". Only processing the first one.");
        }
        if (requestMethods.size() > 1) {
            log.warn(uris.size() + " request methods found for method \"" + method.getName() + "\". Only processing the first one.");
        }
        String uri = uris.get(0).trim();
        Path path = swagger.getPath(uri);
        if (path == null) {
            path = new Path();
            swagger.path(uri, path);
        }
        // Get the method summary from the ApiOperation annotation or use the method name if the annotation doesn't exist.
        String methodSummary = method.getName();
        if (apiOperation != null) {
            methodSummary = apiOperation.value();
        }
        Operation operation = new Operation();
        operation.tag(tagName);
        operation.summary(methodSummary);
        if (javaDocSource.getText() != null) {
            // Process the method description.
            Javadoc javadoc = (Javadoc) javaDocSource.getInternal();
            List<TagElement> tagList = javadoc.tags();
            StringBuilder stringBuilder = new StringBuilder();
            for (TagElement tagElement : tagList) {
                // else available (e.g. @link, etc.).
                if (tagElement.getTagName() == null) {
                    processFragments(tagElement.fragments(), stringBuilder);
                }
            }
            // The string builder has the final method text to use.
            operation.description(stringBuilder.toString());
            setOperationId(tagName, method, operation);
        }
        if (!produces.isEmpty()) {
            operation.setProduces(produces);
        }
        if (!consumes.isEmpty()) {
            operation.setConsumes(consumes);
        }
        // HTTP method MUST be lower cased
        path.set(requestMethods.get(0).name().toLowerCase(), operation);
        // names.
        for (ParameterSource<JavaClassSource> parameterSource : methodSource.getParameters()) {
            processRestMethodParameter(parameterSource, operation, methodParamDescriptions);
        }
        // Process the return value.
        processRestMethodReturnValue(method.getReturnType(), operation, methodParamDescriptions.get("@return"));
    } else {
        log.debug("Skipping method \"" + method.getName() + "\" because it is either not a RequestMapping or it is hidden.");
    }
}