private void buildResponseErrors(Method method, MethodDocument document, JavaMethod javaMethod) {
final DocletTag[] errorStatuses = javaMethod.getTagsByName("error.status");
final DocletTag[] errorCauses = javaMethod.getTagsByName("error.cause");
int totalErrors = errorCauses.length;
if (errorStatuses.length != errorCauses.length) {
LOG.warn(
"For method {}, the number of tags @error.status is different than the"
+ " number of tags @error.cause; Because of this, the {} will only use the minimum"
+ " count from the two.",
method.getName(),
this.getClass().getName());
totalErrors = Math.min(errorCauses.length, errorStatuses.length);
}
List<ResponseError> errors = new ArrayList<ResponseError>(totalErrors);
for (int i = 0; i < totalErrors; i++) {
try {
errors.add(
new ResponseError(
Integer.parseInt(errorStatuses[i].getValue()), errorCauses[i].getValue()));
} catch (NumberFormatException e) {
LOG.error("Invalid number for @error.status: " + errorStatuses[i].getValue());
}
}
document.setResponseErrors(ImmutableList.copyOf(errors));
}
private void buildPath(UriInfo uriInfo, Method method, MethodDocument document) {
final ImmutableList<Path> paths =
this.findAnnotationInMethodAndDeclaringClass(Path.class, method);
final Collection<String> pathsAsString = collectPaths(paths);
StringBuilder pathBuilder = aggregatePaths(uriInfo, pathsAsString);
document.setPath(pathBuilder.toString());
}
@Override
protected void doWithMethodDocument(MethodDocument document, Method method) {
ResourceMethod rm = method.getAnnotation(ResourceMethod.class);
if (rm == null) {
throw new IllegalArgumentException(
"Can't generate document unless method is annotated with @ResourceMethod");
}
MethodParamProcessor mpp = new MethodParamProcessor();
mpp.processAnnotations(method, document);
// --- Process TGIRest annotations
ResourceMethod resourceMethod = method.getAnnotation(ResourceMethod.class);
if (resourceMethod != null) {
document.setDescription(resourceMethod.description());
document.setResponseErrors(getResponseErrors(resourceMethod));
// Parse examples.
document.setExampleDocuments(getExampleDocuments(resourceMethod));
}
}
private void buildQueryAndPathDocuments(
Method method, JavaMethod javaMethod, MethodDocument document) {
if (method.getParameterTypes().length != javaMethod.getParameters().length) {
LOG.error(
"Unable to generate argument documentation: number of method arguments is not "
+ "the same as number of @param found in javadoc.");
return;
}
List<ParamDocument> queryParams = new ArrayList<ParamDocument>();
List<ParamDocument> pathParams = new ArrayList<ParamDocument>();
Annotation[][] annotations = method.getParameterAnnotations();
for (int i = 0; i < annotations.length; i++) {
JavaParameter javaParameter = javaMethod.getParameters()[i];
DocletTag javaParameterTag = javaMethod.getTagsByName("param")[i];
// Check annotations at parameter i
for (Annotation a : annotations[i]) {
if (a.annotationType() == QueryParam.class) {
queryParams.add(
new ParamDocument(
javaParameter.getName(),
extractParameterValue(javaParameterTag, javaParameter.getName())));
} else if (a.annotationType() == PathParam.class) {
pathParams.add(
new ParamDocument(
javaParameter.getName(),
extractParameterValue(javaParameterTag, javaParameter.getName())));
}
}
}
LOG.info("Found {} query params for method {}", queryParams.size(), method.getName());
LOG.info("Found {} path params for method {}", pathParams.size(), method.getName());
document.setQueryParams(ImmutableList.copyOf(queryParams));
document.setPathParams(ImmutableList.copyOf(pathParams));
}
private void buildExamples(JavaMethod javaMethod, MethodDocument document) {
final DocletTag[] exampleTitles = javaMethod.getTagsByName("example.title");
final DocletTag[] exampleDescriptions = javaMethod.getTagsByName("example.description");
final DocletTag[] exampleRequests = javaMethod.getTagsByName("example.request");
final DocletTag[] exampleRequestsContentType =
javaMethod.getTagsByName("example.requestContentType");
final DocletTag[] exampleResponses = javaMethod.getTagsByName("example.response");
final DocletTag[] exampleResponsesContentType =
javaMethod.getTagsByName("example.responseContentType");
if ((exampleTitles.length != exampleDescriptions.length)
|| (exampleTitles.length != exampleRequests.length)
|| (exampleTitles.length != exampleRequestsContentType.length)
|| (exampleTitles.length != exampleResponses.length)
|| (exampleTitles.length != exampleResponsesContentType.length)) {
LOG.error(
"Unable to build examples. The number of tags "
+ "example/title,description,request,requestContentType,response,responseContentType "
+ "must be equal.");
return;
}
List<ApiExampleDocument> examples = new ArrayList<ApiExampleDocument>();
for (int i = 0; i < exampleTitles.length; i++) {
ApiExampleDocument example =
new ApiExampleDocument(
exampleTitles[i].getValue(),
exampleDescriptions[i].getValue(),
exampleRequests[i].getValue(),
exampleRequestsContentType[i].getValue(),
exampleResponses[i].getValue(),
exampleResponsesContentType[i].getValue());
LOG.info("Added new example for {}: {}", document.getPath(), example);
examples.add(example);
}
document.setExampleDocuments(ImmutableList.copyOf(examples));
}
private void buildHttpMethod(Method method, MethodDocument document) {
for (final Annotation a : method.getAnnotations()) {
if (a.annotationType().isAnnotationPresent(HttpMethod.class)) {
// Get the first annotation that has meta-annotation set to
// HttpMethod.
HttpMethod httpMethod = a.annotationType().getAnnotation(HttpMethod.class);
document.setHttpMethod(httpMethod.value());
return;
}
}
throw new IllegalStateException(
"expecting a method annotated with @HttpMethod, but not found.");
}
private void buildDescription(MethodDocument document, JavaMethod javaMethod) {
document.setDescription(javaMethod.getComment());
}
private void buildConsumedMediaTypes(Method method, MethodDocument document) {
final Consumes consumedMediaTypes =
this.findAnnotationInMethodOrDeclaringClass(Consumes.class, method);
document.setMediaTypesConsumed(
Arrays.asList(consumedMediaTypesIfAvailable(consumedMediaTypes)));
}
private void buildProducedMediaTypes(Method method, MethodDocument document) {
final Produces producedMediaTypes =
this.findAnnotationInMethodOrDeclaringClass(Produces.class, method);
document.setMediaTypesProduced(
Arrays.asList(producedMediaTypesIfAvailable(producedMediaTypes)));
}