Improvements to API documentation

Added a section for "Local DNS Records" in API documentation Fixed capitalisation of Pi-hole configuration, which was creating 2 sections in API documentation Amended incorrect description of the until common parameter Signed-off-by: Luis Tavares <[email protected]>
pi-hole · Oct 16, 2024 · 17ae328 · 17ae328
1 parent 3c7b356
commit 17ae328
Show file tree

Hide file tree

Showing 10 changed files with 228 additions and 16 deletions.
diff --git a/src/api/docs/CMakeLists.txt b/src/api/docs/CMakeLists.txt
@@ -39,6 +39,7 @@ set(sources
         hex/specs/search.yaml
         hex/specs/stats.yaml
         hex/specs/teleporter.yaml
+        hex/specs/localdns.yaml
         docs.c
         )
 

diff --git a/src/api/docs/content/specs/clients.yaml b/src/api/docs/content/specs/clients.yaml
@@ -53,7 +53,6 @@ components:
               schema:
                 allOf:
                   - $ref: 'clients.yaml#/components/schemas/clients/put'
-                  - $ref: 'common.yaml#/components/schemas/took'
         responses:
           '201':
             description: Created item
@@ -170,7 +169,6 @@ components:
               schema:
                 allOf:
                   - $ref: 'clients.yaml#/components/schemas/clients/post'
-                  - $ref: 'common.yaml#/components/schemas/took'
         responses:
           '201':
             description: Created item

diff --git a/src/api/docs/content/specs/common.yaml b/src/api/docs/content/specs/common.yaml
@@ -91,7 +91,7 @@ components:
         example: 1672580025
       until:
         in: query
-        description: Unix timestamp from when the data should be requested
+        description: Unix timestamp until when the data should be requested
         name: until
         schema:
           type: integer

diff --git a/src/api/docs/content/specs/config.yaml b/src/api/docs/content/specs/config.yaml
@@ -5,7 +5,7 @@ components:
       get:
         summary: Get current configuration of your Pi-hole
         tags:
-          - "Pi-hole Configuration"
+          - "Pi-hole configuration"
         operationId: "get_config"
         description: |
           This API hook returns infos about the config of your Pi-hole.
@@ -34,7 +34,7 @@ components:
       patch:
         summary: Change configuration of your Pi-hole
         tags:
-          - "Pi-hole Configuration"
+          - "Pi-hole configuration"
         operationId: "patch_config"
         description: |
           This API hook allows to modify the config of your Pi-hole. This endpoint supports changing multiple properties at once when you specify several in the payload. See examples below.
@@ -45,7 +45,6 @@ components:
               schema:
                 allOf:
                   - $ref: 'config.yaml#/components/schemas/config'
-                  - $ref: 'common.yaml#/components/schemas/took'
               examples:
                 config_one:
                   $ref: 'config.yaml#/components/examples/config_one'
@@ -77,7 +76,7 @@ components:
       get:
         summary: Get specific part of current configuration of your Pi-hole
         tags:
-          - "Pi-hole Configuration"
+          - "Pi-hole configuration"
         operationId: "get_config_elem"
         description: |
           This API hook returns infos about the requested subset of your Pi-hole's configuration.
@@ -100,7 +99,7 @@ components:
       put:
         summary: Add config array item
         tags:
-          - "Pi-hole Configuration"
+          - "Pi-hole configuration"
         operationId: "add_array_item"
         description: |
           *Note:* There will be no content on success.
@@ -134,7 +133,7 @@ components:
       delete:
         summary: Delete config array item
         tags:
-          - "Pi-hole Configuration"
+          - "Pi-hole configuration"
         operationId: "delete_array_item"
         description: |
           *Note:* There will be no content on success.

diff --git a/src/api/docs/content/specs/domains.yaml b/src/api/docs/content/specs/domains.yaml
@@ -77,7 +77,6 @@ components:
               schema:
                 allOf:
                   - $ref: 'domains.yaml#/components/schemas/domains/put'
-                  - $ref: 'common.yaml#/components/schemas/took'
         responses:
           '201':
             description: Created domain

diff --git a/src/api/docs/content/specs/localdns.yaml b/src/api/docs/content/specs/localdns.yaml
@@ -0,0 +1,199 @@
+openapi: 3.0.2
+components:
+  paths:
+    record_type:
+      parameters:
+        - $ref: 'localdns.yaml#/components/parameters/record_type'
+      get:
+        summary: Get local DNS records
+        tags:
+          - "Local DNS Records"
+        security: []
+        operationId: "get_records"
+        description: |
+          Get local DNS records (A or CNAME).
+        responses:
+          '200':
+            description: OK
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'localdns.yaml#/components/schemas/record_type'
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/unauthorized'
+                    - $ref: 'common.yaml#/components/schemas/took'
+
+    host_value:
+      parameters:
+        - $ref: 'localdns.yaml#/components/parameters/host_value'
+      put:
+        summary: Add a host record
+        tags:
+          - "Local DNS Records"
+        operationId: "add_host_record"
+        description: |
+          Add a 'host' (A or AAAA) DNS record to the Pi-hole hosts file.
+        responses:
+          '201':
+            description: Created item
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/unauthorized'
+                    - $ref: 'common.yaml#/components/schemas/took'
+      delete:
+        summary: Delete a host record
+        tags:
+          - "Local DNS Records"
+        operationId: "delete_host_record"
+        description: |
+          Remove a host DNS record from the hosts file.
+        responses:
+          '204':
+            description: No Content (deleted)
+          '400':
+            description: Bad request
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/bad_request'
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/unauthorized'
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '404':
+            description: Item not found
+            content:
+              application/json:
+                schema:
+                  $ref: 'common.yaml#/components/schemas/took'
+
+    cname_value:
+      parameters:
+        - $ref: 'localdns.yaml#/components/parameters/cname_value'
+      put:
+        summary: Add a CNAME record
+        tags:
+          - "Local DNS Records"
+        operationId: "add_cname_value"
+        description: |
+          Add a CNAME DNS record to the Pi-hole dnsmaq.conf file.
+        responses:
+          '201':
+            description: Created item
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '400':
+            description: Bad request
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/bad_request'
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/unauthorized'
+                    - $ref: 'common.yaml#/components/schemas/took'
+      delete:
+        summary: Delete a CNAME record
+        tags:
+          - "Local DNS Records"
+        operationId: "delete_cname_value"
+        description: |
+          Delete a local 'CNAME' DNS record
+        responses:
+          '204':
+            description: No Content (deleted)
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  allOf:
+                    - $ref: 'common.yaml#/components/errors/unauthorized'
+                    - $ref: 'common.yaml#/components/schemas/took'
+          '404':
+            description: Item not found
+            content:
+              application/json:
+                schema:
+                  $ref: 'common.yaml#/components/schemas/took'
+
+  parameters:
+    record_type:
+      in: path
+      name: type
+      schema:
+        type: string
+        enum:
+          - hosts
+          - cnameRecords
+      required: true
+      description: The type of DNS record hosts (A) or cnameRecord (CNAME)
+      example: hosts
+    host_value:
+      in: path
+      name: record
+      schema:
+        type: string
+      required: true
+      description: The IP address (IPv4 or IPv6) and domain seperated by a 'SPACE'
+      example: 8.8.8.8 googledns.com
+    cname_value:
+      in: path
+      name: record
+      schema:
+        type: string
+      required: true
+      description: A CSV string with domain, target doomain and TTL
+      example: example.net,pi-hole.net,60
+
+  schemas:
+    record_type:
+      type: object
+      properties:
+        config:
+          type: object
+          properties:
+            dns:
+              type: object
+              properties:
+                # cnameRecords:
+                #   type: array
+                #   items:
+                #     type: string
+                #   example: ["pi.hole,pi-hole.net,60"]
+                hosts:
+                  type: array
+                  items:
+                    type: string
+                  example: ["192.168.0.1 mygateway.local"]
diff --git a/src/api/docs/content/specs/logs.yaml b/src/api/docs/content/specs/logs.yaml
@@ -37,7 +37,7 @@ components:
                       - $ref: 'common.yaml#/components/schemas/took'
       ftl:
         get:
-          summary: Get DNS log content
+          summary: Get FTL information
           tags:
             - "FTL information"
           operationId: "get_ftl_log"
@@ -70,7 +70,7 @@ components:
                       - $ref: 'common.yaml#/components/schemas/took'
       webserver:
         get:
-          summary: Get DNS log content
+          summary: Get HTTP server information
           tags:
             - "FTL information"
           operationId: "get_webserver_log"

diff --git a/src/api/docs/content/specs/main.yaml b/src/api/docs/content/specs/main.yaml
@@ -65,8 +65,8 @@ tags:
     description: Methods used to trigger certain actions on your Pi-hole
   - name: "PADD"
     description: Methods used to query Pi-hole from PADD
-
-
+  - name: "Local DNS Records"
+    description: Methods used to manage A and CNAME records
 
 paths:
   /auth:
@@ -228,6 +228,15 @@ paths:
   /config:
     $ref: 'config.yaml#/components/paths/config'
 
+  /config/dns/{type}:
+    $ref: 'localdns.yaml#/components/paths/record_type'
+
+  /config/dns/hosts/{record}:
+    $ref: 'localdns.yaml#/components/paths/host_value'
+
+  /config/dns/cnameRecords/{record}:
+    $ref: 'localdns.yaml#/components/paths/cname_value'
+
   /config/{element}:
     $ref: 'config.yaml#/components/paths/config_elem'
 

diff --git a/src/api/docs/content/specs/queries.yaml b/src/api/docs/content/specs/queries.yaml
@@ -32,13 +32,13 @@ components:
         parameters:
           - in: query
             name: from
-            description: Get queries from...
+            description: Unix timestamp from when the data should be requested
             required: false
             schema:
               type: number
           - in: query
             name: until
-            description: Get queries until...
+            description: Unix timestamp until when the data should be requested
             required: false
             schema:
               type: number
@@ -114,6 +114,7 @@ components:
             description: Load queries from on-disk database rather than from in-memory
             required: false
             schema:
+              type: boolean
               enum:
                 - true
                 - false

diff --git a/src/api/docs/docs.h b/src/api/docs/docs.h
@@ -136,6 +136,11 @@ static const unsigned char specs_padd_yaml[] = {
 #include "hex/specs/padd.yaml"
 };
 
+static const unsigned char specs_localdns_yaml[] = {
+#include "hex/specs/localdns.yaml"
+};
+
+
 struct {
     const char *path;
     const char *mime_type;
@@ -173,6 +178,7 @@ struct {
     {"specs/teleporter.yaml", "text/plain", (const char*)specs_teleporter_yaml, sizeof(specs_teleporter_yaml)},
     {"specs/action.yaml", "text/plain", (const char*)specs_action_yaml, sizeof(specs_action_yaml)},
     {"specs/padd.yaml", "text/plain", (const char*)specs_padd_yaml, sizeof(specs_padd_yaml)},
+    {"specs/localdns.yaml", "text/plain", (const char*)specs_localdns_yaml, sizeof(specs_localdns_yaml)},
 };
 
 #endif // API_DOCS_H