From: Kevin P. Fleming Date: Mon, 4 Jan 2021 11:49:12 +0000 (-0500) Subject: Add error response objects to all API operations in spec file X-Git-Tag: dnsdist-1.6.0-alpha2~67^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F8999%2Fhead;p=thirdparty%2Fpdns.git 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 --- diff --git a/.github/actions/spell-check/excludes.txt b/.github/actions/spell-check/excludes.txt index 7871a32e1d..13be8b3f69 100644 --- a/.github/actions/spell-check/excludes.txt +++ b/.github/actions/spell-check/excludes.txt @@ -3,6 +3,7 @@ (?:^|/)go\.sum$ (?:^|/)m4/ (?:^|/)package-lock\.json$ +(?:^|/)requirements\.txt$ /expected_result /test-dnsrecords_cc\.cc$ SUMS$ diff --git a/docs/http-api/swagger/authoritative-api-swagger.yaml b/docs/http-api/swagger/authoritative-api-swagger.yaml index eefcaa447b..8c8194792f 100644 --- a/docs/http-api/swagger/authoritative-api-swagger.yaml +++ b/docs/http-api/swagger/authoritative-api-swagger.yaml @@ -1,6 +1,6 @@ swagger: '2.0' info: - version: "0.0.13" + version: "0.0.15" title: PowerDNS Authoritative HTTP API license: name: MIT @@ -23,6 +23,28 @@ security: # We need to look at the code and figure out the default HTTP response # codes and adjust docs accordingly. paths: + '/error': + get: + summary: Will always generate an error + operationId: error + responses: &commonErrors + '400': + description: The supplied request was not valid + schema: + $ref: '#/definitions/Error' + '404': + description: Requested item was not found + schema: + $ref: '#/definitions/Error' + '422': + description: The input to the operation was not valid + schema: + $ref: '#/definitions/Error' + '500': + description: Internal server error + schema: + $ref: '#/definitions/Error' + '/servers': get: summary: List all servers @@ -36,6 +58,7 @@ paths: type: array items: $ref: '#/definitions/Server' + <<: *commonErrors '/servers/{server_id}': get: @@ -54,6 +77,7 @@ paths: description: An server schema: $ref: '#/definitions/Server' + <<: *commonErrors '/servers/{server_id}/cache/flush': put: @@ -77,6 +101,7 @@ paths: description: Flush successful schema: $ref: '#/definitions/CacheFlushResult' + <<: *commonErrors '/servers/{server_id}/zones': get: @@ -111,6 +136,7 @@ paths: type: array items: $ref: '#/definitions/Zone' + <<: *commonErrors post: summary: Creates a new domain, returns the Zone on creation. operationId: createZone @@ -138,6 +164,7 @@ paths: description: A zone schema: $ref: '#/definitions/Zone' + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}': get: @@ -166,6 +193,7 @@ paths: description: A Zone schema: $ref: '#/definitions/Zone' + <<: *commonErrors delete: summary: Deletes this zone, all attached metadata and rrsets. operationId: deleteZone @@ -185,6 +213,7 @@ paths: responses: '204': description: 'Returns 204 No Content on success.' + <<: *commonErrors patch: summary: 'Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success.' operationId: patchZone @@ -209,6 +238,7 @@ paths: responses: '204': description: 'Returns 204 No Content on success.' + <<: *commonErrors put: summary: Modifies basic zone data. @@ -235,6 +265,7 @@ paths: responses: '204': description: 'Returns 204 No Content on success.' + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/notify': put: @@ -257,6 +288,7 @@ paths: responses: '200': description: OK + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/axfr-retrieve': put: @@ -279,6 +311,7 @@ paths: responses: '200': description: OK + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/export': get: @@ -302,6 +335,7 @@ paths: description: OK schema: type: string + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/rectify': put: @@ -326,6 +360,7 @@ paths: description: OK schema: type: string + <<: *commonErrors '/servers/{server_id}/config': get: @@ -346,6 +381,7 @@ paths: type: array items: $ref: '#/definitions/ConfigSetting' + <<: *commonErrors '/servers/{server_id}/config/{config_setting_name}': get: @@ -370,6 +406,7 @@ paths: description: List of config values schema: $ref: '#/definitions/ConfigSetting' + <<: *commonErrors '/servers/{server_id}/statistics': get: @@ -408,6 +445,7 @@ paths: - $ref: '#/definitions/RingStatisticItem' '422': description: 'Returned when a non-existing statistic name has been requested. Contains an error message' + <<: *commonErrors '/servers/{server_id}/search-data': get: @@ -442,6 +480,7 @@ paths: description: Returns a JSON array with results schema: $ref: '#/definitions/SearchResults' + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/metadata': get: @@ -467,6 +506,7 @@ paths: type: array items: $ref: '#/definitions/Metadata' + <<: *commonErrors post: summary: 'Creates a set of metadata entries' description: 'Creates a set of metadata entries of given kind for the zone. Existing metadata entries for the zone with the same kind are not overwritten.' @@ -492,6 +532,7 @@ paths: responses: '204': description: OK + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}': get: @@ -520,6 +561,7 @@ paths: description: Metadata object with list of values schema: $ref: '#/definitions/Metadata' + <<: *commonErrors put: summary: 'Replace the content of a single kind of domain metadata.' description: 'Creates a set of metadata entries of given kind for the zone. Existing metadata entries for the zone with the same kind are removed.' @@ -552,6 +594,7 @@ paths: description: Metadata object with list of values schema: $ref: '#/definitions/Metadata' + <<: *commonErrors delete: summary: 'Delete all items of a single kind of domain metadata.' operationId: deleteMetadata @@ -576,6 +619,7 @@ paths: responses: '200': description: OK + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/cryptokeys': get: @@ -601,6 +645,7 @@ paths: type: array items: $ref: '#/definitions/Cryptokey' + <<: *commonErrors post: summary: 'Creates a Cryptokey' description: 'This method adds a new key to a zone. The key can either be generated or imported by supplying the content parameter. if content, bits and algo are null, a key will be generated based on the default-ksk-algorithm and default-ksk-size settings for a KSK and the default-zsk-algorithm and default-zsk-size options for a ZSK.' @@ -628,6 +673,7 @@ paths: description: Created schema: $ref: '#/definitions/Cryptokey' + <<: *commonErrors '/servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}': get: @@ -656,6 +702,7 @@ paths: description: Cryptokey schema: $ref: '#/definitions/Cryptokey' + <<: *commonErrors put: summary: 'This method (de)activates a key from zone_name specified by cryptokey_id' operationId: modifyCryptokey @@ -685,8 +732,7 @@ paths: responses: '204': description: OK - '422': - description: 'Returned when something is wrong with the content of the request. Contains an error message' + <<: *commonErrors delete: summary: 'This method deletes a key specified by cryptokey_id.' operationId: deleteCryptokey @@ -711,8 +757,7 @@ paths: responses: '204': description: OK - '422': - description: 'Returned when something is wrong with the content of the request. Contains an error message' + <<: *commonErrors '/servers/{server_id}/tsigkeys': parameters: @@ -733,10 +778,7 @@ paths: type: array items: $ref: '#/definitions/TSIGKey' - '500': - description: 'Internal Server Error, keys could not be retrieved. Contains error message' - schema: - $ref: '#/definitions/Error' + <<: *commonErrors post: summary: 'Add a TSIG key' description: 'This methods add a new TSIGKey. The actual key can be generated by the server or be provided by the client' @@ -756,17 +798,10 @@ paths: schema: $ref: '#/definitions/TSIGKey' '409': - description: 'Conflict. A key with this name already exists' - schema: - $ref: '#/definitions/Error' - '422': - description: 'Unprocessable Entry, the TSIGKey provided has issues.' - schema: - $ref: '#/definitions/Error' - '500': - description: 'Internal Server Error. There was a problem creating the key' + description: An item with this name already exists schema: $ref: '#/definitions/Error' + <<: *commonErrors '/servers/{server_id}/tsigkeys/{tsigkey_id}': parameters: @@ -790,14 +825,7 @@ paths: description: OK. schema: $ref: '#/definitions/TSIGKey' - '404': - description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist' - schema: - $ref: '#/definitions/Error' - '500': - description: 'Internal Server Error, keys could not be retrieved. Contains error message' - schema: - $ref: '#/definitions/Error' + <<: *commonErrors put: description: | The TSIGKey at tsigkey_id can be changed in multiple ways: @@ -821,14 +849,11 @@ paths: description: OK. TSIGKey is changed. schema: $ref: '#/definitions/TSIGKey' - '404': - description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist' - schema: - $ref: '#/definitions/Error' - '500': - description: 'Internal Server Error. Contains error message' + '409': + description: An item with this name already exists schema: $ref: '#/definitions/Error' + <<: *commonErrors delete: summary: 'Delete the TSIGKey with tsigkey_id' operationId: deleteTSIGKey @@ -837,14 +862,7 @@ paths: responses: '204': description: 'OK, key was deleted' - '404': - description: 'Not found. The TSIGKey with the specified tsigkey_id does not exist' - schema: - $ref: '#/definitions/Error' - '500': - description: 'Internal Server Error. Contains error message' - schema: - $ref: '#/definitions/Error' + <<: *commonErrors definitions: Server: @@ -1256,7 +1274,7 @@ definitions: Error: title: Error - description: 'Returned when the server encounters an error. Either in client input or internally' + description: 'Returned when the server encounters an error, either in client input or internally' properties: error: type: string diff --git a/docs/requirements.txt b/docs/requirements.txt index d59d77217f..9cf30e4daa 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ Sphinx>=1.5.0,!=1.8.0,<2.0 -git+https://github.com/pieterlexis/sphinxcontrib-openapi@use-jsondomain +git+https://github.com/pieterlexis/sphinxcontrib-openapi@use-jsondomain-pdns git+https://github.com/pieterlexis/sphinx-jsondomain@no-type-links git+https://github.com/pieterlexis/sphinx-changelog@render-tags sphinxcontrib-fulltoc