[Doc] Swagger generated wrong API docs because of the Jackson annotation
- Dominant language
- Java
- Stars
- 15.3k
- Forks
- 3.8k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 160
Description
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/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](https://pulsar.apache.org/admin-rest-api/?version=2.11.0#operation/createNamespace) 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:
```json
"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!
Contributor guide
Research direction
Start with pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/policies/data/AuthPolicies.java and pulsar-common/src/main/java/org/apache/pulsar/client/admin/internal/data/AuthPoliciesImpl.java, then trace how the Swagger document linked in the issue is generated. Compare the generated createNamespace schema with the Jackson-defined field name and verify that the published request example uses namespace_auth.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100