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>

diff --git a/.github/actions/spell-check/excludes.txt b/.github/actions/spell-check/excludes.txt
index 7871a32e1dc9472d29daac512e767e1385190ea6..13be8b3f6960340a03a547913f30ca7070c4a6c9 100644 (file)
--- 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 eefcaa447b1edf868eb9963694f40125b4791004..8c8194792f0d77d04ec96658c84b00a3a81346da 100644 (file)
--- 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 d59d77217f9117e3985ec1b2abd6d7f60077412c..9cf30e4daacf66ab1842398eef1c399e0f4d64e8 100644 (file)
--- 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