apache / apache/pulsar

[Bug] Incorrect swagger specs

Open
#20,164 1 comment 0 reactions 0 assignees View on GitHub
Stale type/bug
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.