[Bug] Incorrect swagger specs
- 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.
### Version
Multiple
### Minimal reproduce step
Generate a client using different swagger.json specs from the distribution here: https://pulsar.apache.org/swagger/
### What did you expect to see?
Given the version (I tried 2.11.1, 2.10.4, 2.10.0, and master) I expected a consistent client library to be created. The only differences should be new features and changed parameters between versions.
Also I expected the Puslar Admin docs [here](https://pulsar.apache.org/admin-rest-api) to match the lastest stable version of Pulsar which is 2.11.1.
### What did you see instead?
Instead I saw that the Pulsar Admin rest api docs offers a download from "master" which leads me to believe that this spec is not genereated from a stable version. Possibly generated from nightly builds (not sure). Comparing the time stamps in the root swagger dist folder (https://pulsar.apache.org/swagger/), the 2.11.1 swagger folder is "2023-04-20 02:29" but the timestamp of "master" is "2023-04-18 07:43". I would expect them to be in sync if they are based on the same version.
There are quite a few inconsistencies between versioned swagger specs and the master swagger spec. One is particular is the endpoint to get a tenant's info - /admin/v2/tenants/{tenant}.
1, The pulsar admin api interface for tagged 2.11.1 is [here](https://github.com/apache/pulsar/blob/v2.11.1/pulsar-client-admin-api/src/main/java/org/apache/pulsar/client/admin/Tenants.java#L79)
2. The master swagger for this endpoint is [here](https://pulsar.apache.org/swagger/master/swagger.json) - search for "Get the admin configuration for a given tenant"
3. The 2.11.1 swagger for this endpoint is [here](https://pulsar.apache.org/swagger/2.11.1/swagger.json) - search for "Get the admin configuration for a given tenant"
Compare the responses between the two versions. Notice that the master version defines a "200" with a return of "TenantInfo", but the 2.11.1 version has no "200" response.
### Anything else?
_No response_
### Are you willing to submit a PR?
- [ ] I'm willing to submit a PR!
Contributor guide
Research direction
Start by comparing the tagged pulsar-client-admin-api/src/main/java/org/apache/pulsar/client/admin/Tenants.java entry with the 2.11.1 and master swagger.json documents linked in the issue. Trace how the versioned and master specs are generated and published. Done means the documented endpoint responses and the Admin REST API download consistently match their corresponding Pulsar versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100