Tripletex / Tripletex/tripletex-api2

Specify additional known responses other than 200 OK in swagger schema

Open
#85 0 comments 0 reactions 0 assignees View on GitHub

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:

image

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:

image

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.