[Doc] Swagger generated wrong API docs because of the Jackson annotation

Search before asking

[X] I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

Recently I tried to replace some pulsar-admin commands with the curl commands, which are much faster because curl is a native binary while pulsar-admin will start a JVM. However, when I followed the API docs here to create a namespace, I found some fields are not set correctly. It took some time to figure out the reason. Eventually, I found the API doc is wrong. We can see the following piece from the request samples:

"auth_policies": {
  "namespaceAuthentication": {},

Unfortunately, it's wrong. The field should be namespace_auth rather than namespaceAuthentication. This doc should be generated by Swagger (not sure). From https://github.com/apache/pulsar/blob/32ad90606062c1eda660037e6277253b35d4a1e6/pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/policies/data/AuthPolicies.java#L29 we can infer that the wrong JSON field name namespaceAuthentication was generated from the AuthPolicies#getNamespaceAuthentication method. However, the field name is actually defined as "namespace_auth" by Jackson, see https://github.com/apache/pulsar/blob/32ad90606062c1eda660037e6277253b35d4a1e6/pulsar-common/src/main/java/org/apache/pulsar/client/admin/internal/data/AuthPoliciesImpl.java#L36

What is your suggestion?

The root cause is that Swagger does not recognise the Jackson annotation @JsonProperty, so it generated the wrong API docs. I'm not familiar with where Pulsar generates the documents currently. But I believe there should be a solution to do that.

Any reference?

No response

Are you willing to submit a PR?

[ ] I'm willing to submit a PR!

apache / pulsar