Examples with ApiComment com.terran4j.commons.api2doc.annotations.ApiComment used on opensource projects

Example 1 with ApiComment

use of com.terran4j.commons.api2doc.annotations.ApiComment in project commons by terran4j.

the class ApiResultObject method getEnumComment.

@SuppressWarnings({ "unchecked", "rawtypes" })
public static final String getEnumComment(Class<?> clazz) {
    if (clazz == null) {
        return null;
    }
    if (!clazz.isEnum()) {
        return null;
    }
    StringBuffer sb = new StringBuffer("\n可选值为：");
    Class<Enum<?>> enumClass = (Class<Enum<?>>) clazz;
    Enum[] enums = enumClass.getEnumConstants();
    for (Enum e : enums) {
        String name = e.name();
        Field field = null;
        try {
            field = enumClass.getDeclaredField(name);
        } catch (NoSuchFieldException | SecurityException e1) {
            log.error("Can't get field \"" + name + "\" from Enum: " + clazz.getName(), e1);
            continue;
        }
        ApiComment comment = field.getAnnotation(ApiComment.class);
        String value = ApiCommentUtils.getComment(comment, null, field.getName());
        if (value == null) {
            value = "";
        }
        if (sb.length() > 0) {
            sb.append("\n");
        }
        sb.append(name).append(": ").append(value).append("; ");
    }
    return sb.toString();
}

Example 2 with ApiComment

use of com.terran4j.commons.api2doc.annotations.ApiComment in project commons by terran4j.

the class Api2DocCollector method toApiFolder.

/**
 * 解析 API 组，一组 API 对应一个 Controller 类， 其中每个 method 对应一个 api 。<br>
 * 只要有 @ApiDoc 注解，有会生成文档，没有这个注解就不会。
 *
 * @param bean
 * @param beanName
 * @return
 */
public ApiFolderObject toApiFolder(Object bean, String beanName) throws BusinessException {
    Class<?> clazz = Classes.getTargetClass(bean);
    Controller controller = AnnotationUtils.findAnnotation(clazz, Controller.class);
    if (controller == null) {
        // 不是 Controller 类，不用收集。
        return null;
    }
    if (log.isInfoEnabled()) {
        log.info("prepare to get API Info by bean:  {}", beanName);
    }
    List<MappingMethod> methods = MappingMethod.getMappingMethods(clazz);
    // Classes.getMethods(RequestMapping.class, clazz);
    if (methods == null || methods.size() == 0) {
        // }
        return null;
    }
    Api2Doc classApi2Doc = clazz.getAnnotation(Api2Doc.class);
    if (classApi2Doc != null && classApi2Doc.ignore()) {
        // 整个类的文档被忽略。
        if (log.isInfoEnabled()) {
            log.info("@Api2Doc ignore = true, no need to get, " + "beanName = {}", beanName);
        }
        return null;
    }
    List<MappingMethod> ali2DocMethods = new ArrayList<>();
    for (MappingMethod mappingMethod : methods) {
        Method method = mappingMethod.getMethod();
        Api2Doc api2Doc = method.getAnnotation(Api2Doc.class);
        if (classApi2Doc == null && api2Doc == null) {
            // 本方法的文档被忽略。
            continue;
        }
        if (api2Doc != null && api2Doc.ignore()) {
            // 本方法的文档被忽略。
            continue;
        }
        ali2DocMethods.add(mappingMethod);
    }
    if (classApi2Doc == null && ali2DocMethods.size() == 0) {
        // 整个类中的方法，都忽略从 API 生成文档，不用收集。
        if (log.isInfoEnabled()) {
            log.info("all method were ignored, no need to get, beanName = {}", beanName);
        }
        return null;
    }
    ApiFolderObject folder = new ApiFolderObject();
    folder.setSourceClass(clazz);
    String id = beanName;
    if (classApi2Doc != null && StringUtils.hasText(classApi2Doc.value())) {
        id = classApi2Doc.value();
    }
    if (classApi2Doc != null && StringUtils.hasText(classApi2Doc.id())) {
        id = classApi2Doc.id();
    }
    folder.setId(id);
    checkId(id);
    String pathPattern = "api2doc/" + id + "/*.md";
    try {
        Resource[] resources = Classes.scanResources(pathPattern);
        if (resources != null && resources.length > 0) {
            Map<String, String> mds = new HashMap<>();
            for (Resource resource : resources) {
                String md = resource.getFilename();
                mds.put(ApiFolderObject.name2Id(md), md);
            }
            folder.setMds(mds);
        }
    } catch (IOException e) {
        String msg = "scan classpath[" + pathPattern + "] failed: " + e.getMessage();
        throw new BeanDefinitionStoreException(msg);
    }
    if (classApi2Doc != null) {
        folder.setOrder(classApi2Doc.order());
    }
    // API 组的名称。
    String name = beanName;
    RequestMapping classMapping = clazz.getAnnotation(RequestMapping.class);
    if (classMapping != null && StringUtils.hasText(classMapping.name())) {
        name = classMapping.name();
    }
    if (classApi2Doc != null && StringUtils.hasText(classApi2Doc.name())) {
        name = classApi2Doc.name();
    }
    folder.setName(name);
    // API 组的注释。
    ApiComment apiComment = clazz.getAnnotation(ApiComment.class);
    folder.setComment(ApiCommentUtils.getComment(apiComment, null, null));
    // 在类上的 seeClass ，是默认的。
    Class<?> defaultSeeClass = ApiCommentUtils.getDefaultSeeClass(apiComment, null);
    // API 组的路径前缀。
    String[] basePaths = getPath(classMapping);
    // 根据方法生成 API 文档。
    List<ApiDocObject> docs = new ArrayList<>();
    for (MappingMethod method : ali2DocMethods) {
        ApiDocObject doc = getApiDoc(method, basePaths, beanName, classApi2Doc, defaultSeeClass);
        if (doc == null) {
            continue;
        }
        String docId = doc.getId();
        ApiDocObject existDoc = folder.getDoc(docId);
        if (existDoc != null) {
            String msg = "文档id值重复： " + docId + "\n" + "如果方法上没有用  @Api2Doc(id = \"xxx\") 来指定文档id，则重载方法会出现此问题。\n" + "请在重载的方法上用 @Api2Doc(id = \"xxx\") 来指定一个不同的文档id";
            throw new BeanDefinitionStoreException(msg);
        }
        docs.add(doc);
        if (log.isInfoEnabled()) {
            log.info("add doc: {}/{}", folder.getId(), docId);
        }
    }
    Collections.sort(docs);
    folder.addDocs(docs);
    return folder;
}

Example 3 with ApiComment

use of com.terran4j.commons.api2doc.annotations.ApiComment in project commons by terran4j.

the class ApiCommentUtils method getComment.

// public static final ApiComment getComment(Field field, Class<?> defaultSeeClass) {
// ApiComment apiComment = field.getAnnotation(ApiComment.class);
// if (apiComment !)
// }
public static final String getComment(ApiComment apiComment, Class<?> defaultSeeClass, String defaultName) {
    if (apiComment != null) {
        String comment = apiComment.value();
        if (StringUtils.hasText(comment)) {
            return comment.trim();
        }
    }
    ApiComment seeComment = getSeeApiComment(apiComment, defaultSeeClass, defaultName);
    if (seeComment == null) {
        return null;
    }
    String comment = seeComment.value();
    if (StringUtils.hasText(comment)) {
        return comment.trim();
    }
    return null;
}

Example 4 with ApiComment

use of com.terran4j.commons.api2doc.annotations.ApiComment in project commons by terran4j.

the class ApiCommentUtils method getSample.

public static final String getSample(ApiComment apiComment, Class<?> defaultSeeClass, String defaultName) {
    if (apiComment != null) {
        String sample = apiComment.sample();
        if (StringUtils.hasText(sample)) {
            return sample.trim();
        }
    }
    ApiComment seeComment = getSeeApiComment(apiComment, defaultSeeClass, defaultName);
    if (seeComment == null) {
        return null;
    }
    String sample = seeComment.sample();
    if (StringUtils.hasText(sample)) {
        return sample.trim();
    }
    return null;
}

Example 5 with ApiComment

use of com.terran4j.commons.api2doc.annotations.ApiComment in project commons by terran4j.

the class ApiCommentUtilsTest method testGetComment.

@Test
public void testGetComment() throws Exception {
    String fieldName = "name";
    Field field = Classes.getField(fieldName, AnotherObject.class);
    ApiComment apiComment = field.getAnnotation(ApiComment.class);
    String comment = ApiCommentUtils.getComment(apiComment, null, fieldName);
    Assert.assertEquals("用户名", comment);
    String sample = ApiCommentUtils.getSample(apiComment, null, fieldName);
    Assert.assertEquals("terran4j", sample);
}