[Bug report] The OpenAPI spec is inaccurate
- 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
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