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

Example 1 with ApiErrors

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

the class Api2DocCollector method getApiDoc.

ApiDocObject getApiDoc(MappingMethod mappingMethod, String[] basePaths, String beanName, Api2Doc classApi2Doc, Class<?> defaultSeeClass) throws BusinessException {
    Method method = mappingMethod.getMethod();
    // 只要有 @ApiDoc 注解（无论是本方法上，还是类上），有会生成文档，没有这个注解就不会。
    Api2Doc api2Doc = method.getAnnotation(Api2Doc.class);
    if (api2Doc == null && classApi2Doc == null) {
        return null;
    }
    ApiDocObject doc = new ApiDocObject();
    doc.setSourceMethod(method);
    // 获取文档的 id，以 @Api2Doc、方法名 为顺序获取。
    String id = method.getName();
    if (api2Doc != null && StringUtils.hasText(api2Doc.value())) {
        id = api2Doc.value();
    }
    if (api2Doc != null && StringUtils.hasText(api2Doc.id())) {
        id = api2Doc.id();
    }
    doc.setId(id);
    checkId(id);
    // 获取文档的排序。
    if (api2Doc != null) {
        doc.setOrder(api2Doc.order());
    }
    // 获取文档名称，按 @Api2Doc 、@Mapping、方法名的顺序获取。
    String name = method.getName();
    String mappingName = mappingMethod.getName();
    if (StringUtils.hasText(mappingName)) {
        name = mappingName;
    }
    if (api2Doc != null && StringUtils.hasText(api2Doc.name())) {
        name = api2Doc.name();
    }
    doc.setName(name);
    // 获取 API 的注释信息。
    ApiComment apiComment = method.getAnnotation(ApiComment.class);
    defaultSeeClass = ApiCommentUtils.getDefaultSeeClass(apiComment, defaultSeeClass);
    String docComment = ApiCommentUtils.getComment(apiComment, defaultSeeClass, name);
    doc.setComment(docComment);
    String docSample = ApiCommentUtils.getSample(apiComment, defaultSeeClass, name);
    doc.setSample(docSample);
    // 获取 API 的访问路径。
    String[] paths = mappingMethod.getPath();
    paths = combine(basePaths, paths);
    doc.setPaths(paths);
    // 获取 HTTP 方法。
    doc.setMethods(mappingMethod.getRequestMethod());
    // 收集参数信息。
    List<ApiParamObject> apiParams = toApiParams(method, defaultSeeClass);
    if (apiParams != null && apiParams.size() > 0) {
        for (ApiParamObject apiParam : apiParams) {
            doc.addParam(apiParam);
        }
    }
    // 收集返回值信息。
    KeyedList<String, ApiResultObject> totalResults = new KeyedList<>();
    ApiResultObject resultObject = ApiResultObject.parseResultType(method, totalResults);
    if (resultObject != null) {
        resultObject.setComment(docComment);
        resultObject.setSample(docSample);
    }
    doc.setResultType(resultObject);
    doc.setResults(totalResults.getAll());
    // 确定返回类型的描述。
    String returnTypeDesc = null;
    List<ApiResultObject> results = doc.getResults();
    if (results != null && results.size() > 0) {
        ApiResultObject result = results.get(0);
        ApiDataType dataType = result.getDataType();
        if (dataType != null) {
            if (dataType == ApiDataType.ARRAY) {
                returnTypeDesc = result.getSourceType().getSimpleName() + "[]";
            } else {
                returnTypeDesc = result.getSourceType().getSimpleName();
            }
        }
    }
    if (returnTypeDesc == null) {
        Class<?> returnType = doc.getSourceMethod().getReturnType();
        if (returnType != null && returnType != void.class) {
            returnTypeDesc = returnType.getSimpleName();
        }
    }
    doc.setReturnTypeDesc(returnTypeDesc);
    // 收集错误码信息。
    ApiErrors errorCodes = method.getAnnotation(ApiErrors.class);
    if (errorCodes != null && errorCodes.value() != null && errorCodes.value().length > 0) {
        for (ApiError errorCode : errorCodes.value()) {
            ApiErrorObject error = getError(errorCode);
            if (error == null) {
                continue;
            }
            doc.addError(error);
        }
    } else {
        ApiError errorCode = method.getAnnotation(ApiError.class);
        ApiErrorObject error = getError(errorCode);
        if (error != null) {
            doc.addError(error);
        }
    }
    return doc;
}