apache / apache/pulsar

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

Open
#19,941 1 comment 0 reactions 0 assignees View on GitHub
doc-required Stale
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.