]> git.ipfire.org Git - thirdparty/pdns.git/commit
Add error response objects to all API operations in spec file 8999/head
authorKevin P. Fleming <kevin@km6g.us>
Mon, 4 Jan 2021 11:49:12 +0000 (06:49 -0500)
committerKevin P. Fleming <kevin@km6g.us>
Mon, 4 Jan 2021 11:49:12 +0000 (06:49 -0500)
commit20287c91d1c6f2605f7a669a4c42dc5b7c75e291
tree2333b7ad985add5feeab5b05a758da87a6ed2c8a
parente33706e91fdef560e325b2ca746cca08c6fad73d
Add error response objects to all API operations in spec file

This patch documents the possible error response objects for all API
operations. When a spec-validating client is used, returning a
response code (and object) which are not included in the spec will
disallow access to the response object, and may cause an exception to
be thrown.

In order to do this without repeating the possible responses for each
API operation, the YAML anchor/alias mechanism is used so that the
list of response codes and their object schemas can be written in one
place. To make that possible, the patch adds a fictitious '/error' API
operation, which of course will actually return an error since it does
not exist.

The spec version has been bumped from 0.0.13 to 0.0.15 (0.0.14 should
have been used for the recent bug fixes to the spec file).

Note: If the spec file was upgraded to OpenAPI 3.0.0, instead of
Swagger 2.0, the response codes could be specified as '4XX' and '5XX',
which would cover all possible response codes in those ranges without
having to audit the code for error responses.

Signed-off-by: Kevin P. Fleming <kevin@km6g.us>
.github/actions/spell-check/excludes.txt
docs/http-api/swagger/authoritative-api-swagger.yaml
docs/requirements.txt