apache / apache/gravitino

[Bug report] The OpenAPI spec is inaccurate

Open
#6,072 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Java
Stars
3.2k
Forks
935
Avg merge
1d 16h
Merged PRs (30d)
298

Description

### Version

main branch

### Describe what's wrong

The OpenAPI spec (`/docs/open-api/*.yaml`) is not accurate. This inaccuracy may lead to incomplete/insufficient parameter validation or even security issues.

For example, for the `registerModel` operation, the `ModelRegisterRequest` has `name` listed under `required`. This is fine. We mentioned that the "name cannot be empty" in `description`, which is also good. However, the word "empty" is ambiguous. We'd better add an explicit constraint like `minLength: 1`.

In the same spirit, we may add a pattern for the `name` field. For example, I don't think `" \/ "` is a good/valid name for a model. We may want to restrict the maximum length of a name.

There are also other more generic issues such as the use of `PUT` and `PATCH` verbs.
A `PUT` is supposed to be a fully replace request, i.e. replace an existing resource with a new one. A `PATCH`, on the other hand, is supposed to be a partial update request. However, in our current API specs, we are using `PUT` for `PATCH`.

### Error message and/or stacktrace

N/A

### How to reproduce

N/A

### Additional context

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the OpenAPI files under /docs/open-api/*.yaml, focusing on the registerModel operation and its ModelRegisterRequest schema. Compare documented constraints such as required, minLength, patterns, and maximum lengths with the API behavior, then review the use of PUT and PATCH; done means the specifications accurately describe validation and update semantics.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
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.