Display JSON and protobuf request and response specification in DocService

[ikhoon]

Motivation:

A @RequestObject bean can be converted as a specification of an
annotated service. Neither response nor POJO request are shown in a
DocService. Only gRPC and Thrift DocService can display the full
specifications of input and output types.

This PR aims to generalize a way to create a StructInfo from a range
of types by offering NamedTypeInfoProvider which can be dynamically
loaded via SPI or explicitly set using DocServiceBuilder.
A data type that depends on a specific library, such as protobuf,
Thrift, ScalaPB can extend this interface and inject custom
implementations.

Modifications:

• Designed NamedTypeInfoProvider interface to let users customize how to
  create a StructInfo from the given type descriptor.
  The following implementations are added for the default behavior.
  • JsonNamedTypeInfoProvider
  • ThriftNamedTypeInfoProvider
  • ProtobufNamedTypeInfoProvider
  • ScalaPbNamedTypeInfoProvider
• Add DocServiceBuilder.nameTypeInfoProvider() in order to override
  the default NamedTypeInfoProviders.
• Moved some code related to StructInfo in *DocServicePlugin to
  *NamedTypeInfoProvider

Result:

• You can now see the specification of an annotated service made of a JSON
  object or protobuf can be viewed in DocService.
• Fixes Provide a way to support StructInfo for various types #4309

[codecov]

Codecov Report

Merging #4322 (53475b1) into master (3da7bac) will increase coverage by 0.10%.
The diff coverage is 83.70%.

@@             Coverage Diff              @@
##             master    #4322      +/-   ##
============================================
+ Coverage     73.93%   74.04%   +0.10%     
- Complexity    17856    18082     +226     
============================================
  Files          1516     1527      +11     
  Lines         66405    67010     +605     
  Branches       8347     8460     +113     
============================================
+ Hits          49099    49620     +521     
- Misses        13287    13331      +44     
- Partials       4019     4059      +40     

Impacted Files	Coverage Δ
...linecorp/armeria/server/docs/DocServicePlugin.java	20.00% <ø> (ø)
...om/linecorp/armeria/server/docs/NamedTypeInfo.java	100.00% <ø> (ø)
...orp/armeria/server/docs/NamedTypeInfoProvider.java	0.00% <0.00%> (ø)
...ver/protobuf/ProtobufRequestConverterFunction.java	77.52% <ø> (ø)
...obuf/ProtobufRequestConverterFunctionProvider.java	92.85% <ø> (+25.00%)	⬆️
...ver/annotated/kotlin/MarkdownDescriptionService.kt	29.41% <25.00%> (ø)
...inecorp/armeria/server/docs/DocServiceBuilder.java	73.91% <36.36%> (-2.91%)	⬇️
...om/linecorp/armeria/server/docs/ExceptionInfo.java	57.14% <45.00%> (-9.53%)	⬇️
...ava/com/linecorp/armeria/server/docs/EnumInfo.java	44.18% <45.83%> (+6.25%)	⬆️
...armeria/internal/server/annotation/KotlinUtil.java	71.11% <50.00%> (-1.51%)	⬇️
... and 86 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[jrhee17]

Looks nice overall! Only got to look at the annotated doc part today, will take a closer look tomorrow 🙏

[minwoox]

Looks great. 👍

[ikhoon]

This PR is ready to review. 😄

[ikhoon]

@cnabro You may be interested in the changes of this PR.

[ikhoon]

Releasing is just around the corner. I rescheduled this features to 1.19.0.

[minwoox]

Looks great!
Thanks! 👍 👍 👍

[cnabro]

I've been waiting for this feature 👍👍

[jrhee17]

Q) I'm failing to understand the need for this NamedTypeInfoProvider 😅

As far as I understand, the dependency :scalapb_2.13 implies inclusion of :protobuf, which means both ScalaPbNamedTypeInfoProvider and ProtobufNamedTypeInfoProvider are included as DocService#spiNamedTypeInfoProviders.

Since it's undefined which NamedTypeInfoProvider will be applied first (and they seem to be essentially doing the same thing), I was wondering why we define a separate NamedTypeInfoProvider here.

[ikhoon]

ScalaPbNamedTypeInfoProvider extracts protobuf Descriptor from GeneratedMessage and GeneratedSealedOneof using reflections and delegate it to ProtobufNamedTypeInfoProvider.
If GeneratedMessage is given to ProtobufNamedTypeInfoProvider, null is returned by ProtobufNamedTypeInfoProvider.

[jrhee17]

If GeneratedMessage is given to ProtobufNamedTypeInfoProvider, null is returned by ProtobufNamedTypeInfoProvider.

Sorry 😅 I wasn't able to understand this point. Would you mind pointing out where GeneratedMessage yields null?

armeria/protobuf/src/main/java/com/linecorp/armeria/server/protobuf/ProtobufNamedTypeInfoProvider.java

Lines 87 to 109 in 5b3f3f1

	public NamedTypeInfo newNamedTypeInfo(Object typeDescriptor) {
	requireNonNull(typeDescriptor, "typeDescriptor");
	if (typeDescriptor instanceof Descriptor) {
	return newStructInfo((Descriptor) typeDescriptor);
	}
	if (typeDescriptor instanceof EnumDescriptor) {
	return newEnumInfo((EnumDescriptor) typeDescriptor);
	}
	if (!(typeDescriptor instanceof Class)) {
	return null;
	}
	final Class<?> clazz = (Class<?>) typeDescriptor;
	if (!isProtobufMessage(clazz)) {
	return null;
	}
	final Message.Builder messageBuilder = getMessageBuilder(clazz);
	final Descriptor descriptorForType = messageBuilder.getDescriptorForType();
	return newStructInfo(descriptorForType).withAlias(clazz.getName());
	}

[ikhoon]

scalapb.GeneratedMessage is not a subclass of com.google.protobuf.Message so isProtobufMessage() returns false for scalapb.GeneratedMessage.

armeria/protobuf/src/main/java/com/linecorp/armeria/server/protobuf/ProtobufNamedTypeInfoProvider.java

Lines 102 to 104 in 11ee1ff

	if (!isProtobufMessage(clazz)) {
	return null;
	}

[ikhoon]

Added some tests 61dd8c0 (#4322) in order to check your concerns. :-)

[minwoox]

People who use DocServic as the API spec will love this feature. Thanks! 😄

[minwoox]

@ikhoon Could you fix the conflict? 😄

[ikhoon]

Fixed. 😉

[jrhee17]

Thanks @ikhoon ! 👍 🙇 👍