[Doc] all the links to the admin REST API reference doc are broken

[jak78]

Search before asking

• I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

Description

There are links to the API reference documentation in the admin API documentation. They are generated by @inject instructions in the markdown files.

Since Pulsar 3, each of these links is broken. Indeed, since Pulsar 3, in the API reference documentation, the operation names have changed. For example: getSchema has become SchemasResource_getSchema. This change has caused all the links generated by @inject from the markdown documentation to be broken.

My estimate: more than 180 links are broken.

Example

admin-api-schemas.md

Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/getSchema?version=@pulsar:version_number@}

Genrated display

Generated link on Pulsar 2.11. docs

https://pulsar.apache.org/admin-rest-api?version=2.11.1&apiversion=v2#operation/getSchema

This link works because the operation on the Pulsar 2.x API reference doc is getSchema

Generated link on Pulsar 3.1.1 docs

https://pulsar.apache.org/admin-rest-api?version=3.1.1&apiversion=v2#operation/getSchema

This link does not work because the operation on the Pulsar 3.x API reference doc is SchemasResource_getSchema instead of getSchema

What is your suggestion?

I have no better idea than fixing the operation name on each of 188 @injectoccurence. This is tedious. Feel free to suggest a better idea.

Any reference?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[tisonkun]

This is the root cause #19193

cc @poorbarcode

We previously have duplicate endpoint anchor, but after this change, the links get broken. However, the {{ClassName}} part cannot be inferred, so one solution is we update the content of @inject from {{methodName}} to {{ClassName}}_{{methodName}} one by one..

[lhotari]

also related #20164

[lhotari]

There's a fix in apache/pulsar-site#970, however since the operation names aren't unique, the links to swagger docs won't always go to the correct anchor.