Support markdown when using @Description Annotation #4304

cnabro · 2022-06-18T18:03:36Z

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/

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 · 2022-06-18T18:03:40Z

All committers have signed the CLA.

codecov · 2022-06-18T19:43:13Z

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. 😄

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

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

docs-client/src/lib/specification.tsx

site/src/pages/docs/server-docservice.mdx

cnabro · 2022-06-22T05:42:00Z

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

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

cnabro · 2022-06-23T07:47:30Z

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

@minwoox @ikhoon

minwoox · 2022-06-23T13:43:24Z

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 · 2022-06-23T14:20:44Z

@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 · 2022-06-23T14:51:31Z

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 · 2022-06-24T01:28:52Z

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 · 2022-06-24T01:47:40Z

@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 · 2022-06-24T01:55:34Z

How about fixing the issue like this screenshot using scroll?

That looks awesome. 😆

minwoox · 2022-06-24T03:32:02Z

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 · 2022-06-24T03:56:51Z

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

….java Co-authored-by: jrhee17 <guins_j@guins.org>

…tion/AnnotatedDocServiceTest.java Co-authored-by: jrhee17 <guins_j@guins.org>

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

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

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

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

docs-client/src/components/Description/index.tsx

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

…tion/AnnotatedDocServicePlugin.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…riptionInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…nfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

….java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…tion/AnnotatedDocServiceTest.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…riptionInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

….java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…ription.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

ikhoon

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

core/src/main/java/com/linecorp/armeria/server/docs/Markup.java

site/src/pages/docs/server-docservice.mdx

core/src/main/java/com/linecorp/armeria/server/docs/DescriptionInfo.java

...ft0.13/src/main/java/com/linecorp/armeria/internal/server/thrift/ThriftDocServicePlugin.java

ikhoon · 2022-07-20T10:51:07Z

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

@@ -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,


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

OK. I'll wait for it 👍

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…nInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

…nInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

ikhoon · 2022-07-29T03:21:40Z

Thanks a lot for your hard work! ❤️

cnabro requested review from ikhoon, jrhee17, minwoox and trustin as code owners June 18, 2022 18:03

cnabro marked this pull request as draft June 18, 2022 18:03

cnabro force-pushed the feature/support-markdown-docservice branch 3 times, most recently from 0c273bf to 6e39005 Compare June 18, 2022 18:37

cnabro force-pushed the feature/support-markdown-docservice branch from 4e288f2 to b76cd63 Compare June 19, 2022 07:01

ikhoon added the new feature label Jun 19, 2022

cnabro marked this pull request as ready for review June 19, 2022 14:47

minwoox reviewed Jun 22, 2022

View reviewed changes

minwoox added this to the 1.17.0 milestone Jun 22, 2022

ikhoon reviewed Jun 22, 2022

View reviewed changes

...src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedDocServicePlugin.java Outdated Show resolved Hide resolved

cnabro force-pushed the feature/support-markdown-docservice branch from 92163ad to e89486d Compare June 23, 2022 09:58

cnabro marked this pull request as draft June 24, 2022 14:09

cnabro force-pushed the feature/support-markdown-docservice branch 2 times, most recently from aa1edeb to ea2e4f6 Compare June 24, 2022 17:07

cnabro and others added 2 commits July 18, 2022 14:20

Update core/src/main/java/com/linecorp/armeria/server/docs/StructInfo…

ee9b92f

….java Co-authored-by: jrhee17 <guins_j@guins.org>

Update core/src/test/java/com/linecorp/armeria/internal/server/annota…

4e375d9

…tion/AnnotatedDocServiceTest.java Co-authored-by: jrhee17 <guins_j@guins.org>

ikhoon reviewed Jul 20, 2022

View reviewed changes

cnabro and others added 15 commits July 20, 2022 10:23

Update core/src/main/java/com/linecorp/armeria/internal/server/annota…

8ffd0a3

…tion/AnnotatedDocServicePlugin.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/internal/server/annota…

82eb4a4

…tion/AnnotatedDocServicePlugin.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/annotation/Desc…

7eefbde

…riptionInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update docs-client/src/components/Description/index.tsx

340ed8a

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update docs-client/src/components/Description/index.tsx

d7e1446

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/NamedTypeI…

908d9a1

…nfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/MethodInfo…

12ee0ef

….java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/test/java/com/linecorp/armeria/internal/server/annota…

87f9094

…tion/AnnotatedDocServiceTest.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/EnumInfo.java

2c21197

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/annotation/Desc…

62c273e

…riptionInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/StructInfo…

ee8a068

….java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/annotation/Desc…

00a3145

…ription.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Change DescriptionInfo package

76db094

Fix typescript lint error

db3ab11

Fix scala lint

d2f2b3e

ikhoon mentioned this pull request Jul 20, 2022

Extract Javadoc of a request and a response object in an annotated service for the documantation of DocService #4357

Open

ikhoon approved these changes Jul 20, 2022

View reviewed changes

ikhoon reviewed Jul 20, 2022

View reviewed changes

cnabro and others added 7 commits July 20, 2022 20:03

Update core/src/main/java/com/linecorp/armeria/server/docs/Markup.java

fe4cfc1

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/Descriptio…

923bd05

…nInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update site/src/pages/docs/server-docservice.mdx

6ff92e5

Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Update core/src/main/java/com/linecorp/armeria/server/docs/Descriptio…

1b6a75d

…nInfo.java Co-authored-by: Ikhun Um <ih.pert@gmail.com>

Fix lints

685af5e

Fix error when descriptionInfo is undefined.

51de424

Fix site render error

5e465ff

ikhoon merged commit f01b02b into line:master Jul 29, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support markdown when using @Description Annotation #4304

Support markdown when using @Description Annotation #4304

cnabro commented Jun 18, 2022 •

edited

Loading

CLAassistant commented Jun 18, 2022 •

edited

Loading

codecov bot commented Jun 18, 2022 •

edited

Loading

minwoox left a comment

cnabro commented Jun 22, 2022

cnabro commented Jun 23, 2022

minwoox commented Jun 23, 2022 •

edited

Loading

cnabro commented Jun 23, 2022 •

edited

Loading

cnabro commented Jun 23, 2022 •

edited

Loading

minwoox commented Jun 24, 2022

cnabro commented Jun 24, 2022 •

edited

Loading

minwoox commented Jun 24, 2022

minwoox commented Jun 24, 2022

cnabro commented Jun 24, 2022 •

edited

Loading

ikhoon left a comment

ikhoon Jul 20, 2022

cnabro Jul 20, 2022

ikhoon commented Jul 29, 2022

Support markdown when using @Description Annotation #4304

Support markdown when using @Description Annotation #4304

Conversation

cnabro commented Jun 18, 2022 • edited Loading

CLAassistant commented Jun 18, 2022 • edited Loading

codecov bot commented Jun 18, 2022 • edited Loading

Codecov Report

minwoox left a comment

Choose a reason for hiding this comment

cnabro commented Jun 22, 2022

cnabro commented Jun 23, 2022

minwoox commented Jun 23, 2022 • edited Loading

cnabro commented Jun 23, 2022 • edited Loading

cnabro commented Jun 23, 2022 • edited Loading

minwoox commented Jun 24, 2022

cnabro commented Jun 24, 2022 • edited Loading

minwoox commented Jun 24, 2022

minwoox commented Jun 24, 2022

cnabro commented Jun 24, 2022 • edited Loading

ikhoon left a comment

Choose a reason for hiding this comment

ikhoon Jul 20, 2022

Choose a reason for hiding this comment

cnabro Jul 20, 2022

Choose a reason for hiding this comment

ikhoon commented Jul 29, 2022

cnabro commented Jun 18, 2022 •

edited

Loading

CLAassistant commented Jun 18, 2022 •

edited

Loading

codecov bot commented Jun 18, 2022 •

edited

Loading

minwoox commented Jun 23, 2022 •

edited

Loading

cnabro commented Jun 23, 2022 •

edited

Loading

cnabro commented Jun 23, 2022 •

edited

Loading

cnabro commented Jun 24, 2022 •

edited

Loading

cnabro commented Jun 24, 2022 •

edited

Loading