Search in sources :

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();
}
Also used : Field(java.lang.reflect.Field) ApiComment(com.terran4j.commons.api2doc.annotations.ApiComment)

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;
}
Also used : BeanDefinitionStoreException(org.springframework.beans.factory.BeanDefinitionStoreException) Resource(org.springframework.core.io.Resource) Method(java.lang.reflect.Method) IOException(java.io.IOException) Controller(org.springframework.stereotype.Controller) RequestMapping(org.springframework.web.bind.annotation.RequestMapping) Api2Doc(com.terran4j.commons.api2doc.annotations.Api2Doc) ApiComment(com.terran4j.commons.api2doc.annotations.ApiComment)

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;
}
Also used : ApiComment(com.terran4j.commons.api2doc.annotations.ApiComment)

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;
}
Also used : ApiComment(com.terran4j.commons.api2doc.annotations.ApiComment)

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);
}
Also used : Field(java.lang.reflect.Field) ApiComment(com.terran4j.commons.api2doc.annotations.ApiComment) Test(org.junit.Test)

Aggregations

ApiComment (com.terran4j.commons.api2doc.annotations.ApiComment)12 Field (java.lang.reflect.Field)5 Api2Doc (com.terran4j.commons.api2doc.annotations.Api2Doc)3 Method (java.lang.reflect.Method)3 ArrayList (java.util.ArrayList)3 PropertyDescriptor (java.beans.PropertyDescriptor)2 BeanDefinitionStoreException (org.springframework.beans.factory.BeanDefinitionStoreException)2 ApiError (com.terran4j.commons.api2doc.annotations.ApiError)1 ApiErrors (com.terran4j.commons.api2doc.annotations.ApiErrors)1 ApiDataType (com.terran4j.commons.api2doc.domain.ApiDataType)1 ApiObject (com.terran4j.commons.api2doc.domain.ApiObject)1 FlexibleString (com.terran4j.commons.api2doc.impl.FlexibleString)1 KeyedList (com.terran4j.commons.util.value.KeyedList)1 IOException (java.io.IOException)1 Parameter (java.lang.reflect.Parameter)1 HashMap (java.util.HashMap)1 List (java.util.List)1 Map (java.util.Map)1 Test (org.junit.Test)1 Resource (org.springframework.core.io.Resource)1