Support markdown when using @Description Annotation

[cnabro]

Motivation:

• Support markdown when using @description Annotation
• Armeria DocService can be extended and used for various purposes

Modifications:

• Provide a way to improve DocService for annotated service #4299 (comment)

• Support varius markup

  • markdown
    • react-markdown
    • react-syntax-highlighter
    • remark-gfm
    • github-markdown-css
  • mermaid.js

• Support enums documentation in annotated service.

• Support return types documentation in annotated service using annotation.

  • Add @ResponseObject to specify which element should be converted to structs in DocService by AnnotatedDocServicePlugin
  • Need to be exclude default class like HttpResponse ..
  • 👉 Rollbacked by Provide a way to support StructInfo for various types #4309, it will be fixed using StructInfoProvider

• Show path mappings in Services

• Update Armeria Reference doc : https://armeria.dev/docs/server-docservice/

<img width=1681" alt="image" src="https://user-images.githubusercontent.com/6916639/174469675-daa21c8a-6fd3-40c0-bd78-0c538bdfcf0c.png">

Result:

• Closes [Provide a way to improve DocService for annotated service #4299, The return type of annotated service does not show anything in DocService #2200]
• Support Markdown Description
• Support Enums&Return Types documentation in annotated service

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

Merging #4304 (5e465ff) into master (8b0225e) will decrease coverage by 0.05%.
The diff coverage is 75.00%.

@@             Coverage Diff              @@
##             master    #4304      +/-   ##
============================================
- Coverage     73.57%   73.52%   -0.06%     
- Complexity    17654    17665      +11     
============================================
  Files          1500     1504       +4     
  Lines         65991    66094     +103     
  Branches       8325     8335      +10     
============================================
+ Hits          48555    48597      +42     
- Misses        13236    13287      +51     
- Partials       4200     4210      +10     

Impacted Files	Coverage Δ
...linecorp/armeria/server/docs/DocServicePlugin.java	20.00% <ø> (ø)
...om/linecorp/armeria/server/docs/NamedTypeInfo.java	100.00% <ø> (ø)
...ver/annotated/kotlin/MarkdownDescriptionService.kt	29.41% <29.41%> (ø)
...nal/server/annotation/AnnotatedServiceFactory.java	92.12% <40.00%> (-0.74%)	⬇️
...va/com/linecorp/armeria/server/docs/FieldInfo.java	60.52% <50.00%> (-3.37%)	⬇️
...ava/com/linecorp/armeria/server/docs/EnumInfo.java	37.93% <60.00%> (ø)
.../linecorp/armeria/server/docs/DescriptionInfo.java	66.66% <66.66%> (ø)
...linecorp/armeria/server/docs/FieldInfoBuilder.java	70.00% <66.66%> (ø)
...rver/annotated/kotlin/MermaidDescriptionService.kt	66.66% <66.66%> (ø)
...l/server/annotation/AnnotatedDocServicePlugin.java	82.47% <68.42%> (-0.94%)	⬇️
... and 52 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8b0225e...5e465ff. Read the comment docs.

[minwoox]

This looks really amazing. Thanks a lot, @cnabro! 😄
Do you mind adding test cases of ResponseObject and Description to Java test class especially to AnnotatedDocServiceTest?
We use the class as a playground of DocService using the env value (DOC_SERVICE_DEMO) so it would be very helpful if we can use it there. 😄

[cnabro]

@minwoox ok, i'll try it. Thanks for the review ! 👍

[cnabro]

As mentioned in Slack,
Rollback @ResponseObject for #4309. And I added some test-case for AnnotatedDocServiceTest.

@minwoox @ikhoon

[minwoox]

I found out that the markdown String is not properly rendered when the page has a scroll. We need to fix that or we can probably just disable markdown for the parameter and struct description.

Do you think it's worth supporting markdown in the parameter description as well?

[cnabro]

@minwoox I think worth supporting markdown in the parameter description as well 😅
It's easy to express the specification like Deprecated,removed or See this link and etc..

[cnabro]

And I found the same issue on previous version (on disabled markdown). I think it's not a markdown issue.

I think the workaround is not use table, or customize <TableCell> for resizing.
(There is so much to express in table 🐤)

Markdown is already support resizing.

[minwoox]

And I found the same issue on previous version (on disabled markdown). I think it's not a markdown issue

Oops, I didn't know that we had such a bug. 😓

I think the workaround is not use table

Then which one do you want to use instead? Could you tell me more about this, please? 😄

[cnabro]

@minwoox
After write comments, I found out some solution.
Wrapping <Table> with <TableContainer> will be adjust overflowX

https://github.com/mui/material-ui/blob/v4.9.0/packages/material-ui/src/TableContainer/TableContainer.js#L10

<TableContainer> // wrapping table
        <Table>
        <TableHead>
          <TableRow>
            <TableCell>Name</TableCell>
            {hasLocation && <TableCell>Location</TableCell>}
            <TableCell>Required</TableCell>
            <TableCell>Type</TableCell>
            <TableCell>Description</TableCell>
            {hasBean && <TableCell />}
          </TableRow>
        </TableHead>
        <TableBody>
          <FieldInfos
            hasLocation={hasLocation}
            indent={0}
            title={title}
            variables={variables}
            specification={specification}
          />
        </TableBody>
      </Table>
      </TableContainer>

How about fixing the issue like this screenshot using scroll?

[minwoox]

How about fixing the issue like this screenshot using scroll?

That looks awesome. 😆

[minwoox]

Had a chat with @trustin and how about adding a metadata to @Description so that we can support various markup such as Mermaid.js?

@Description(value= "...", markup = Markup.NONE)
@Description(value= "...", markup = Markup.MARKDOWN)
@Description(value= "...", markup = Markup.MERMAID) // we can add this later.

[cnabro]

@minwoox Good idea. It will be used for various purposes. 👍
I'll try to add a metadata for @Description

[ikhoon]

Awesome, @cnabro! 🚀💯
As you know, documentation service is the most beloved feature.
Many Armeria users will be happy with this.

[ikhoon]

Note: This method will be changed by #4322.
I'd like to ask @cnabro for a review after they are merged.

[cnabro]

OK. I'll wait for it 👍

[ikhoon]

Thanks a lot for your hard work! ❤️