[fix] [doc] fix multiple apis in the automatically generated documentation use the same anchor point

[poorbarcode]

Motivation

Now that site admin-rest-api is automatically generated through swagger, each API in the site has its own link that we can walk through, the generated rule of API-link is https://pulsar.apache.org/admin-rest-api/#operation/{operationId}, we call the suffix #operation/{operationId} of link anchor.

Since the {operationId}'s default value is the method name of the endpoint class, and there has the same method name in the multi endpoint-classes, such as Namespaces.setDispatchRate and PersistentTopics.setDispatchRate, so these both APIs will generate the same link: https://pulsar.apache.org/admin-rest-api/#operation/setDispatchRate.

Modifications

In the update to version 3.1.8 of swagger-maven-plugin, there are another ways to set operationId: The Operation Id Format. see https://github.com/kongchen/swagger-maven-plugin/blob/e4cf3af6ed4a4987b2269a05b7037549bc4a5511/src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java#L535-L540. So we can generate operationId using the specified rule {className}_{methodName}.

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

Matching PR in forked repository

PR in forked repository:

• [ci] [fix] [doc] fix multiple apis in the automatically generated document poorbarcode/pulsar#51

[dave2wave]

These look like actual API changes. Please explain.

[poorbarcode]

Hi @dave2wave

These look like actual API changes. Please explain.

Already changed the plain to only modify Swagger annotations. please take a look again

[mattisonchao]

@tisonkun What do you think about this PR? I am unfamiliar with swagger, but I know you have recently worked on this part. please help to review it, thanks!

[tisonkun]

I agree that it's not a breaking change for end-users but only affects the doc experience.

Some related works previous:

• [fix][doc] Stablize swagger docs #19025
• [fix][client] ExtNonPersistentTopics and prevent prefix match #19065
• [fix][doc] Rename LedgerInfo to avoid swagger docs conflict #19087

And I agree that a nickname alias can be a better solution. I can approve this move but I appreciate seeing the discussion on the mailing list continue for a while (days or after the lunar new year holiday).

cc @tuteng @shoothzj

[hezhangjian]

Now we aggregate rest api into a single file. I think it might be better to split them. This is also good for us to generate other language admin clients. I am trying to work on it.

[github-actions]

The pr had no activity for 30 days, mark with Stale label.

[poorbarcode]

@tisonkun @tuteng @heesung-sn

Please take a look, thanks

[poorbarcode]

/pulsarbot rerun-failure-checks

[poorbarcode]

/pulsarbot rerun-failure-checks

[poorbarcode]

/pulsarbot rerun-failure-checks

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.31%. Comparing base (af1360f) to head (e414067).
⚠️ Report is 2761 commits behind head on master.

Additional details and impacted files

@@              Coverage Diff              @@
##             master   #19193       +/-   ##
=============================================
+ Coverage     26.40%   62.31%   +35.91%     
+ Complexity     6427     3503     -2924     
=============================================
  Files          1597     1848      +251     
  Lines        123682   135866    +12184     
  Branches      13511    14952     +1441     
=============================================
+ Hits          32658    84665    +52007     
+ Misses        86336    43466    -42870     
- Partials       4688     7735     +3047     

Flag	Coverage Δ
inttests	24.53% <ø> (-0.05%)	⬇️
systests	25.28% <ø> (?)
unittests	59.54% <ø> (+42.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1364 files with indirect coverage changes

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

[heesung-sohn]

nit: Is this json outputFormats necessary?

[poorbarcode]

nit: Is this json outputFormats necessary?

It should be optional, but maven or swagger had issues, and I had null Pointers when testing locally. I tried troubleshooting the issue yesterday but couldn't get the root cause quickly, so I thought adding this configuration would avoid unnecessary trouble.

[heesung-sohn]

nit: I think {className}_{methodName} is reasonable as the unique operationIdFormat.

LGTM if we don't have duplicated apiSources from the same class and methodName.

[poorbarcode]

After keeping only the latest version of admin API(such as v2, v3), {className}_{methodName} will not conflict. If we open multiple versions of API in the future, we need to change the rule to {package_name}_{className}_{methodName}

[tisonkun]

Please take a look at the OWASP failure. Although it seems unrelated to this patch, we should fix it later.

[poorbarcode]

Hi @tisonkun

Please take a look at the OWASP failure. Although it seems unrelated to this patch, we should fix it later.

I have pushed a #19764 to fix it, so I am merging the current PR now.