Tripletex / Tripletex/tripletex-api2
Specify additional known responses other than 200 OK in swagger schema
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 49
- Forks
- 47
- Avg merge
- 1h 1m
- Merged PRs (30d)
- 1
Description
Tripletex's schema describes 200 OK responses, like this:
but it is lacking in regards to describing the other expected responses like 401, 422 etc. This results in generated clients[^2] not knowing of all responses an operation may yield, in this case it has no knowledge of any errors:
If I understand swagger's doc^1 correctly it would be appropriate to include other common responses too:
Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By "known errors" we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.
[^2]: Example https://openapi-ts.pages.dev/
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the Swagger/OpenAPI schema definitions for the operations that currently describe only 200 responses. Review the documented common error responses, including 401 and 422, and verify that generated clients can see the known responses for each operation. Done means the schema describes successful responses and the known errors relevant to those operations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100