Allow style customization in the documentation service #6235

Ivan-Montes · 2025-05-09T06:10:30Z

Related: #5900

Motivation:

This change addresses feedback from multiple users requesting the ability to customize the appearance of the documentation service. The customizable elements now include:

Title
Browser tab title
Header bar background color
Color for the GotoSelect component
Buttons colors in the Debug component

Modifications:

Backend

In DocServiceBuilder, add a Map to store relevant data and a builder method for the documentation title.
In DocService, modify the constructor to include a new attribute.
In Static Nested SpecificationLoader, adjust the constructor and the generateServiceSpecification method.
In ServiceSpecification, create a private Map and add Getter and Setter methods.

Frontend

In lib/specification.tsx, include a Record<String, String> attribute in the SpecificationData interface.
In lib/colors.tsx, add reusable method to validate color hex code.
In containers/App/index.tsx, retrieve the style settings and applied them to the app's title and header.
In components/GotoSelect/index.tsx, apply color using inline style.
In containers/MethodPage/index.tsx, apply the custom color styling.
In containers/MethodPage/DebugPage.tsx, apply custom button color styling via inline styles.

Result:

We can now customize the appearance of:

Title
Browser tab title
Header bar background color
Color for the GotoSelect component
Buttons colors in the Debug component

Main view

Debug modal

github-actions · 2025-05-09T07:23:38Z

🔍 Build Scan® (commit: `c25ee87`)

Job name	Status	Build Scan®
build-ubicloud-standard-16-jdk-8	✅	https://ge.armeria.dev/s/25x2rmpuq3qx2
build-ubicloud-standard-16-jdk-21-snapshot-blockhound	✅	https://ge.armeria.dev/s/hmqezy6pbbxma
build-ubicloud-standard-16-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/afmitsxs3gkqk
build-ubicloud-standard-16-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/uucqt6zz2ps5a
build-ubicloud-standard-16-jdk-17-leak	✅	https://ge.armeria.dev/s/zsf3trethtoty
build-ubicloud-standard-16-jdk-11	✅	https://ge.armeria.dev/s/euwz5lzpmgxw2
build-macos-latest-jdk-21	✅	https://ge.armeria.dev/s/zfhnd2t63ubya

codecov · 2025-05-12T00:36:30Z

Codecov Report

Attention: Patch coverage is 82.85714% with 12 lines in your changes missing coverage. Please review.

Project coverage is 74.67%. Comparing base (8150425) to head (c25ee87).
Report is 105 commits behind head on main.

Files with missing lines	Patch %	Lines
...inecorp/armeria/server/docs/DocServiceBuilder.java	12.50%	7 Missing ⚠️
...ria/server/docs/DocServiceInjectedScriptsUtil.java	90.74%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #6235      +/-   ##
============================================
+ Coverage     74.46%   74.67%   +0.21%     
- Complexity    22234    22561     +327     
============================================
  Files          1963     1981      +18     
  Lines         82437    83275     +838     
  Branches      10764    10828      +64     
============================================
+ Hits          61385    62188     +803     
- Misses        15918    15931      +13     
- Partials       5134     5156      +22

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

Ivan-Montes · 2025-05-15T13:21:41Z

I think this approach aligns better with your suggestions now. Let me know what you think!

We can now customize the appearance of:

Header title
Header bar background color
Color for the GotoSelect component
Browser tab title
Browser tab favicon

jrhee17

Overall looks good, left only nits

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

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

jrhee17 · 2025-05-20T07:41:20Z

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

+     * @param url the input string to escape
+     * @return the escaped string
+     */
+    private static String escapeForJavaScriptUrl(String url) {


Question) Would it make sense to use URLEncoder.encode(url, "UTF-8") instead?

Yes, it's definitely a more convenient method.

I ultimately had to use a different approach because the href attribute of the <link> HTML tag didn’t correctly interpret the value generated by the URLEncoder.encode(url, "UTF-8") method, and the icon wasn't displayed.

docs-client/src/containers/App/index.tsx

--- Related: line#5900 **Motivation:** This change addresses feedback from multiple users requesting the ability to customize the appearance of the documentation service. The customizable elements now include: - Title - Browser tab title - Header bar background color - Color for the `GotoSelect` component - Buttons colors in the `Debug` component **Modifications:** Backend - In `DocServiceBuilder`, add a `Map` to store relevant data and a builder method for the documentation title. - In `DocService`, modify the constructor to include a new attribute. - In Static Nested `SpecificationLoader`, adjust the constructor and the `generateServiceSpecification` method. - In `ServiceSpecification`, create a private `Map` and add Getter and Setter methods. Frontend - In `lib/specification.tsx`, include a `Record<String, String>` attribute in the `SpecificationData` interface. - In `lib/colors.tsx`, add reusable method to validate color hex code. - In `containers/App/index.tsx`, retrieve the style settings and applied them to the app's title and header. - In `components/GotoSelect/index.tsx`, apply color using inline style. - In `containers/MethodPage/index.tsx`, apply the custom color styling. - In `containers/MethodPage/DebugPage.tsx`, apply custom button color styling via inline styles. **Result:** We can now customize the appearance of: - Title - Browser tab title - Header bar background color - Color for the `GotoSelect` component - Buttons colors in the `Debug` component

…pts` --- Related: line#5900 **Motivation:** This change addresses feedback from multiple users requesting the ability to customize the appearance of the documentation service. The customizable elements now include: - Header title - Header bar background color - Color for the `GotoSelect` component - Browser tab title - Browser tab favicon **Modifications:** Backend - In `DocServiceBuilder`, add a `Map` to store relevant data and a builder method for the documentation title. - In `DocService`, modify the constructor to include a new attribute. - In Static Nested `SpecificationLoader`, adjust the constructor and the `generateServiceSpecification` method. - In `ServiceSpecification`, create a private `Map` and add Getter and Setter methods. - In `DocServiceInjectedScriptsUtil`, add methods to generate customization scripts. - In `DocServiceInjectedScriptsUtilTest`, develop tests for the above logic. Frontend - In `lib/specification.tsx`, include a `Record<String, String>` attribute in the `SpecificationData` interface. - In `containers/App/index.tsx`, retrieve the title and apply it to the app's titles. Add JS hook class. - In `components/GotoSelect/index.tsx`, add JS hook class for custom behavior. **Result:** - Closes: line#5900 We can now customize the appearance of: - Header title - Header bar background color - Color for the `GotoSelect` component - Browser tab title - Browser tab favicon

Ivan-Montes requested review from ikhoon, jrhee17, minwoox and trustin as code owners May 9, 2025 06:10

jrhee17 reviewed May 12, 2025

View reviewed changes

core/src/main/java/com/linecorp/armeria/server/docs/DocServiceBuilder.java Outdated Show resolved Hide resolved

Ivan-Montes force-pushed the feature/allow-custom-doc-service branch from ce4d1cc to 37379c0 Compare May 15, 2025 10:48

jrhee17 reviewed May 20, 2025

View reviewed changes

Ivan-Montes added 3 commits May 23, 2025 12:19

feat: add improvements from maintainers

c25ee87

Ivan-Montes force-pushed the feature/allow-custom-doc-service branch from 37379c0 to c25ee87 Compare May 23, 2025 10:22

github-actions bot added the Stale label Jun 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow style customization in the documentation service #6235

Allow style customization in the documentation service #6235

Uh oh!

Ivan-Montes commented May 9, 2025

Uh oh!

github-actions bot commented May 9, 2025 •

edited

Loading

Uh oh!

codecov bot commented May 12, 2025 •

edited

Loading

Uh oh!

Uh oh!

Ivan-Montes commented May 15, 2025

Uh oh!

jrhee17 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrhee17 May 20, 2025

Uh oh!

Ivan-Montes May 21, 2025

Uh oh!

Ivan-Montes May 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Allow style customization in the documentation service #6235

Are you sure you want to change the base?

Allow style customization in the documentation service #6235

Uh oh!

Conversation

Ivan-Montes commented May 9, 2025

Uh oh!

github-actions bot commented May 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Build Scan® (commit: c25ee87)

Uh oh!

codecov bot commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Ivan-Montes commented May 15, 2025

Uh oh!

jrhee17 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrhee17 May 20, 2025

Choose a reason for hiding this comment

Uh oh!

Ivan-Montes May 21, 2025

Choose a reason for hiding this comment

Uh oh!

Ivan-Montes May 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented May 9, 2025 •

edited

Loading

🔍 Build Scan® (commit: `c25ee87`)

codecov bot commented May 12, 2025 •

edited

Loading