Support markdown when using @Description Annotation

core/src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedDocServicePlugin.java

@@ -41,7 +41,6 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
@@ -61,14 +60,17 @@
 import com.linecorp.armeria.server.RoutePathType;
 import com.linecorp.armeria.server.Service;
 import com.linecorp.armeria.server.ServiceConfig;
+import com.linecorp.armeria.server.annotation.Description;
 import com.linecorp.armeria.server.annotation.Header;
 import com.linecorp.armeria.server.annotation.Param;
 import com.linecorp.armeria.server.annotation.RequestObject;
+import com.linecorp.armeria.server.docs.DescriptionInfo;
 import com.linecorp.armeria.server.docs.DocServiceFilter;
 import com.linecorp.armeria.server.docs.DocServicePlugin;
 import com.linecorp.armeria.server.docs.EndpointInfo;
 import com.linecorp.armeria.server.docs.EndpointInfoBuilder;
 import com.linecorp.armeria.server.docs.EnumInfo;
+import com.linecorp.armeria.server.docs.EnumValueInfo;
 import com.linecorp.armeria.server.docs.FieldInfo;
 import com.linecorp.armeria.server.docs.FieldInfoBuilder;
 import com.linecorp.armeria.server.docs.FieldLocation;
@@ -128,7 +130,7 @@ public ServiceSpecification generateSpecification(Set<ServiceConfig> serviceConf
         requireNonNull(filter, "filter");
 
         final Map<Class<?>, Set<MethodInfo>> methodInfos = new HashMap<>();
-        final Map<Class<?>, String> serviceDescription = new HashMap<>();
+        final Map<Class<?>, DescriptionInfo> serviceDescription = new HashMap<>();
         serviceConfigs.forEach(sc -> {
             final AnnotatedService service = sc.service().as(AnnotatedService.class);
             if (service != null) {
@@ -145,7 +147,7 @@ public ServiceSpecification generateSpecification(Set<ServiceConfig> serviceConf
         return generate(serviceDescription, methodInfos);
     }
 
-    private static void addServiceDescription(Map<Class<?>, String> serviceDescription,
+    private static void addServiceDescription(Map<Class<?>, DescriptionInfo> serviceDescription,
                                               AnnotatedService service) {
         final Class<?> clazz = service.object().getClass();
         serviceDescription.computeIfAbsent(clazz, AnnotatedServiceFactory::findDescription);
@@ -164,8 +166,9 @@ private static void addMethodInfo(Map<Class<?>, Set<MethodInfo>> methodInfos,
                 httpMethod -> {
                     final MethodInfo methodInfo = new MethodInfo(
                             name, returnTypeSignature, fieldInfos, ImmutableList.of(), // Ignore exceptions.
-                            ImmutableList.of(endpoint), httpMethod, AnnotatedServiceFactory
-                                    .findDescription(method));
+                            ImmutableList.of(endpoint), httpMethod,
+                            AnnotatedServiceFactory.findDescription(method));
+
                     methodInfos.computeIfAbsent(clazz, unused -> new HashSet<>()).add(methodInfo);
                 });
     }
@@ -284,8 +287,9 @@ private static FieldInfo fieldInfo(AnnotatedValueResolver resolver) {
                          .location(location(resolver))
                          .requirement(resolver.shouldExist() ? FieldRequirement.REQUIRED
                                                              : FieldRequirement.OPTIONAL);
-        if (resolver.description() != null) {
-            builder.docString(resolver.description());
+        final DescriptionInfo description = resolver.description();
+        if (description != null) {
+            builder.descriptionInfo(description);
         }
         return builder.build();
     }
@@ -371,6 +375,10 @@ static TypeSignature toTypeSignature(Type type) {
             return TypeSignature.ofList(toTypeSignature(clazz.getComponentType()));
         }
 
+        if (clazz.isEnum()) {
+            return TypeSignature.ofNamed(clazz);
+        }
+
         return TypeSignature.ofBase(clazz.getSimpleName());
     }
 
@@ -388,7 +396,7 @@ private static FieldLocation location(AnnotatedValueResolver resolver) {
     }
 
     @VisibleForTesting
-    static ServiceSpecification generate(Map<Class<?>, String> serviceDescription,
+    static ServiceSpecification generate(Map<Class<?>, DescriptionInfo> serviceDescription,
                                          Map<Class<?>, Set<MethodInfo>> methodInfos) {
         final Set<ServiceInfo> serviceInfos = methodInfos
                 .entrySet().stream()
@@ -409,22 +417,64 @@ private static NamedTypeInfo newNamedTypeInfo(TypeSignature typeSignature) {
         }
 
         if (type.isEnum()) {
-            @SuppressWarnings("unchecked")
-            final Class<? extends Enum<?>> enumType = (Class<? extends Enum<?>>) type;
-            return new EnumInfo(enumType);
+            return newEnumInfo(type);
         }
 
         return newStructInfo(type);
     }
 
+    private static EnumInfo newEnumInfo(Class<?> enumClass) {
+        final String name = enumClass.getName();
+        final Description description = AnnotationUtil.findFirst(enumClass, Description.class);
+
+        final Field[] declaredFields = enumClass.getDeclaredFields();
+        final List<EnumValueInfo> values =
+                Stream.of(declaredFields)
+                      .filter(Field::isEnumConstant)
+                      .map(f -> {
+                          final Description valueDescription = AnnotationUtil.findFirst(f, Description.class);
+                          if (valueDescription != null) {
+                              return new EnumValueInfo(f.getName(), null,
+                                                       DescriptionInfo.of(valueDescription.value(),
+                                                                          valueDescription.markup()));
+                          }
+
+                          return new EnumValueInfo(f.getName(), null);
+                      })
+                      .collect(toImmutableList());
+
+        if (description != null) {
+            return new EnumInfo(name, values, DescriptionInfo.of(description.value(), description.markup()));
+        }
+
+        return new EnumInfo(name, values);
+    }
+
     private static StructInfo newStructInfo(Class<?> structClass) {
         final String name = structClass.getName();
+        final Description description = AnnotationUtil.findFirst(structClass, Description.class);
 
         final Field[] declaredFields = structClass.getDeclaredFields();
         final List<FieldInfo> fields =
                 Stream.of(declaredFields)
-                      .map(f -> FieldInfo.of(f.getName(), toTypeSignature(f.getGenericType())))
-                      .collect(Collectors.toList());
+                      .map(f -> {
+                          final Description fieldDescription = AnnotationUtil.findFirst(f, Description.class);
+                          if (fieldDescription != null) {
+                              return FieldInfo.of(
+                                      f.getName(),
+                                      toTypeSignature(f.getGenericType()),
+                                      DescriptionInfo.of(fieldDescription.value(), fieldDescription.markup())
+                              );
+                          }
+
+                          return FieldInfo.of(f.getName(), toTypeSignature(f.getGenericType()));
+                      })
+                      .collect(toImmutableList());
+
+        if (description != null) {
+            return new StructInfo(name, fields, DescriptionInfo.of(description.value(), description.markup()));
+        }
+
         return new StructInfo(name, fields);
     }
 

core/src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedServiceFactory.java

@@ -103,6 +103,7 @@
 import com.linecorp.armeria.server.annotation.ResponseConverterFunction;
 import com.linecorp.armeria.server.annotation.StatusCode;
 import com.linecorp.armeria.server.annotation.Trace;
+import com.linecorp.armeria.server.docs.DescriptionInfo;
 
 /**
  * Builds a list of {@link AnnotatedService}s from an {@link Object}.
@@ -582,14 +583,14 @@ private static <T extends Annotation, R> Builder<R> getAnnotatedInstances(
      * Returns the description of the specified {@link AnnotatedElement}.
      */
     @Nullable
-    static String findDescription(AnnotatedElement annotatedElement) {
+    static DescriptionInfo findDescription(AnnotatedElement annotatedElement) {
         requireNonNull(annotatedElement, "annotatedElement");
         final Description description = AnnotationUtil.findFirst(annotatedElement, Description.class);
         if (description != null) {
             final String value = description.value();
             if (DefaultValues.isSpecified(value)) {
                 checkArgument(!value.isEmpty(), "value is empty.");
-                return value;
+                return DescriptionInfo.of(description.value(), description.markup());
             }
         } else if (annotatedElement instanceof Parameter) {
             // JavaDoc/KDoc descriptions only exist for method parameters
@@ -600,7 +601,8 @@ static String findDescription(AnnotatedElement annotatedElement) {
             final String propertyName = executable.getName() + '.' + parameter.getName();
             final Properties cachedProperties = DOCUMENTATION_PROPERTIES_CACHE.getIfPresent(fileName);
             if (cachedProperties != null) {
-                return cachedProperties.getProperty(propertyName);
+                final String propertyValue = cachedProperties.getProperty(propertyName);
+                return propertyValue != null ? DescriptionInfo.of(propertyValue) : null;
             }
             try (InputStream stream = AnnotatedServiceFactory.class.getClassLoader()
                                                                    .getResourceAsStream(fileName)) {
@@ -610,7 +612,9 @@ static String findDescription(AnnotatedElement annotatedElement) {
                 final Properties properties = new Properties();
                 properties.load(stream);
                 DOCUMENTATION_PROPERTIES_CACHE.put(fileName, properties);
-                return properties.getProperty(propertyName);
+
+                final String propertyValue = properties.getProperty(propertyName);
+                return propertyValue != null ? DescriptionInfo.of(propertyValue) : null;
             } catch (IOException exception) {
                 logger.warn("Failed to load an API description file: {}", fileName, exception);
             }

core/src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedValueResolver.java

@@ -94,6 +94,7 @@
 import com.linecorp.armeria.server.annotation.RequestConverterFunctionProvider;
 import com.linecorp.armeria.server.annotation.RequestObject;
 import com.linecorp.armeria.server.annotation.StringRequestConverterFunction;
+import com.linecorp.armeria.server.docs.DescriptionInfo;
 
 import io.netty.handler.codec.http.HttpConstants;
 import scala.concurrent.ExecutionContext;
@@ -440,7 +441,7 @@ private static AnnotatedValueResolver of(AnnotatedElement annotatedElement,
         requireNonNull(objectResolvers, "objectResolvers");
         requireNonNull(dependencyInjector, "dependencyInjector");
 
-        final String description = findDescription(annotatedElement);
+        final DescriptionInfo description = findDescription(annotatedElement);
         final Param param = annotatedElement.getAnnotation(Param.class);
         if (param != null) {
             final String name = findName(param, typeElement);
@@ -534,7 +535,7 @@ private static void warnOnDuplicateResolver(Executable constructorOrMethod,
     private static AnnotatedValueResolver ofPathVariable(String name,
                                                          AnnotatedElement annotatedElement,
                                                          AnnotatedElement typeElement, Class<?> type,
-                                                         @Nullable String description) {
+                                                         @Nullable DescriptionInfo description) {
         return new Builder(annotatedElement, type)
                 .annotationType(Param.class)
                 .httpElementName(name)
@@ -548,7 +549,7 @@ private static AnnotatedValueResolver ofPathVariable(String name,
     private static AnnotatedValueResolver ofQueryParam(String name,
                                                        AnnotatedElement annotatedElement,
                                                        AnnotatedElement typeElement, Class<?> type,
-                                                       @Nullable String description,
+                                                       @Nullable DescriptionInfo description,
                                                        @Nullable String serviceQueryDelimiter) {
         String queryDelimiter = serviceQueryDelimiter;
         final Delimiter delimiter = annotatedElement.getAnnotation(Delimiter.class);
@@ -574,7 +575,7 @@ private static AnnotatedValueResolver ofQueryParam(String name,
     private static AnnotatedValueResolver ofFileParam(String name,
                                                       AnnotatedElement annotatedElement,
                                                       AnnotatedElement typeElement, Class<?> type,
-                                                      @Nullable String description) {
+                                                      @Nullable DescriptionInfo description) {
         return new Builder(annotatedElement, type)
                 .annotationType(Param.class)
                 .httpElementName(name)
@@ -589,7 +590,7 @@ private static AnnotatedValueResolver ofFileParam(String name,
     private static AnnotatedValueResolver ofHeader(String name,
                                                    AnnotatedElement annotatedElement,
                                                    AnnotatedElement typeElement, Class<?> type,
-                                                   @Nullable String description) {
+                                                   @Nullable DescriptionInfo description) {
         return new Builder(annotatedElement, type)
                 .annotationType(Header.class)
                 .httpElementName(name)
@@ -607,7 +608,7 @@ private static AnnotatedValueResolver ofRequestObject(AnnotatedElement annotated
                                                           Class<?> type, Set<String> pathParams,
                                                           List<RequestObjectResolver> objectResolvers,
                                                           DependencyInjector dependencyInjector,
-                                                          @Nullable String description) {
+                                                          @Nullable DescriptionInfo description) {
         // To do recursive resolution like a bean inside another bean, the original object resolvers should
         // be passed into the AnnotatedBeanFactoryRegistry#register.
         final BeanFactoryId beanFactoryId = AnnotatedBeanFactoryRegistry.register(
@@ -892,7 +893,7 @@ private static Type parameterizedTypeOf(AnnotatedElement element) {
     private final Object defaultValue;
 
     @Nullable
-    private final String description;
+    private final DescriptionInfo description;
 
     private final BiFunction<AnnotatedValueResolver, ResolverContext, Object> resolver;
 
@@ -911,7 +912,7 @@ private AnnotatedValueResolver(@Nullable Class<? extends Annotation> annotationT
                                    @Nullable Class<?> containerType, Class<?> elementType,
                                    @Nullable ParameterizedType parameterizedElementType,
                                    @Nullable String defaultValue,
-                                   @Nullable String description,
+                                   @Nullable DescriptionInfo description,
                                    BiFunction<AnnotatedValueResolver, ResolverContext, Object> resolver,
                                    @Nullable BeanFactoryId beanFactoryId,
                                    AggregationStrategy aggregationStrategy) {
@@ -987,7 +988,7 @@ Object defaultValue() {
     }
 
     @Nullable
-    String description() {
+    DescriptionInfo description() {
         return description;
     }
 
@@ -1067,7 +1068,7 @@ private static final class Builder {
         private boolean supportContainer;
         private boolean supportDefault;
         @Nullable
-        private String description;
+        private DescriptionInfo description;
         @Nullable
         private BiFunction<AnnotatedValueResolver, ResolverContext, Object> resolver;
         @Nullable
@@ -1135,7 +1136,7 @@ private Builder typeElement(AnnotatedElement typeElement) {
         /**
          * Sets the description of the {@link AnnotatedElement}.
          */
-        private Builder description(@Nullable String description) {
+        private Builder description(@Nullable DescriptionInfo description) {
             this.description = description;
             return this;
         }

core/src/main/java/com/linecorp/armeria/server/annotation/Description.java

@@ -22,6 +22,8 @@
 import java.lang.annotation.Target;
 
 import com.linecorp.armeria.internal.server.annotation.DefaultValues;
+import com.linecorp.armeria.server.docs.DocService;
+import com.linecorp.armeria.server.docs.Markup;
 
 /**
  * An annotation used in annotated HTTP service. This describes:
@@ -32,11 +34,16 @@
  * </ul>
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER })
+@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD })
 public @interface Description {
 
     /**
      * The description of a type, a field, a method or a parameter.
      */
     String value() default DefaultValues.UNSPECIFIED;
+
+    /**
+     * The supported markup type in {@link DocService}.
+     */
+    Markup markup() default Markup.NONE;
 }