API Documentation fixes

[irsheep]

What does this PR aim to accomplish?:

Fix some typos in the API documentation and add a new section

How does this PR accomplish the above?:

Fixed an incorrect description in the "until" parameter, it was using the same description as "from"
Fixed capitalization of "Pi-hole configuration", which was creating 2 sections in API documentation, "Pi-hole Configuration" and "Pi-hole configuration"
Added a section for "Local DNS Records" with examples how to add and remove "A" and "CNAME" records.
Removed "$ref: 'common.yaml#/components/schemas/took'" from requestBody

Link documentation PRs if any are needed to support this PR:

N/A

---

By submitting this pull request, I confirm the following:

1. I have read and understood the contributors guide, as well as this entire template. I understand which branch to base my commits and Pull Requests against.
2. I have commented my proposed changes within the code and I have tested my changes.
3. I am willing to help maintain this change if there are issues with it later.
4. It is compatible with the EUPL 1.2 license
5. I have squashed any insignificant commits. (git rebase)
6. I have checked that another pull request for this purpose does not exist.
7. I have considered, and confirmed that this submission will be valuable to others.
8. I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
9. I give this submission freely, and claim no ownership to its content.

---

• I have read the above and my PR is ready for review. Check this box to confirm

Has been addressed

[DL6ER]

Thank you for your submission. The spell check found a small glitch, see below.

To be honest, I am not sure how I feel about adding dedicated documentation for local DNS records where /config is already documented. Yes, I see how you are getting here (making it more obvious) but one might then come and ask why we are doing it for local DNS records and local CNAMEs but not for other array-like settings (e.g., DNS upstream servers) where the same PUT/DELETE can be used.

Also, there is some glitch when you leave the field empty, you get the full config instead:

[irsheep]

Thank you for your submission. The spell check found a small glitch, see below.

To be honest, I am not sure how I feel about adding dedicated documentation for local DNS records where /config is already documented. Yes, I see how you are getting here (making it more obvious) but one might then come and ask why we are doing it for local DNS records and local CNAMEs but not for other array-like settings (e.g., DNS upstream servers) where the same PUT/DELETE can be used.

Also, there is some glitch when you leave the field empty, you get the full config instead:

Sorry didn't intended to close your comment without addressing this.

When I was implementing this change I thought about the same, but decided to propose it anyway for a couple of reasons

• In the previous version of Pi-hole A and CNAME records had their own API (and only realized that this is part of /config after it was almost done)
• The path to update or delete the DNS records requires 4 elements in the path /config/dns/_type_/_record_ , but that is not clear in the Pi-hole configuration section
• to document that format when specifying the record. An A record uses a space "IP fqdn" and CNAME uses a comma. At first I was thinking that it was a mistake, but then realized that this is because how it written to the hosts and dnsmask files.

This one might be cheeky because just found now, the same could be said with DNS control

As for the glitch that is because as you mention proposed Local DNS records section part of the /config so by leaving the type blank in that request you're in fact requesting /config/dns.

[DL6ER]

As for the glitch that is because as you mention proposed Local DNS records section part of the /config so by leaving the type blank in that request you're in fact requesting /config/dns.

Yes, I know :-) My comment was more meant into the direction "is there any way to prevent this from happening?". I could have been clearer about my intention. As you have dedicated PUT/DELETE descriptions, you may do the same for GET and avoid the parameter {type]. Otherwise, I do seem to recall that there was once a mentioning of the parameter property allowEmptyValue as in

  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
      allowEmptyValue: false                                 <-----------------------

but I haven't tested it myself.

An A record uses a space "IP fqdn" and CNAME uses a comma.

Ah yes, right. That is in the description of pihole.toml and can also be queried over the API but it isn't obvious at all from the very generic/abstract OpenAPI format how the particular formatting of the individual endpoints would be.

Or, of course, you don't need to know it at all if you are using https://pi.hole/admin/settings/dnsrecords which does everything for you (if configuring via the web interface).

document that format

Where did you add something describing this? I have only see the examples.

[irsheep]

As for the glitch that is because as you mention proposed Local DNS records section part of the /config so by leaving the type blank in that request you're in fact requesting /config/dns.

Yes, I know :-) My comment was more meant into the direction "is there any way to prevent this from happening?". I could have been clearer about my intention. As you have dedicated PUT/DELETE descriptions, you may do the same for GET and avoid the parameter {type]. Otherwise, I do seem to recall that there was once a mentioning of the parameter property allowEmptyValue as in

  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
      allowEmptyValue: false                                 <-----------------------

but I haven't tested it myself.

An A record uses a space "IP fqdn" and CNAME uses a comma.

Ah yes, right. That is in the description of pihole.toml and can also be queried over the API but it isn't obvious at all from the very generic/abstract OpenAPI format how the particular formatting of the individual endpoints would be.

Or, of course, you don't need to know it at all if you are using https://pi.hole/admin/settings/dnsrecords which does everything for you (if configuring via the web interface).

document that format

Where did you add something describing this? I have only see the examples.

I looked at the allowEmptyValue and it doesn't seem to work, I do agree with your suggestion to have the GET method added for each of the record types, it might make is less ambiguous.

It is in the description/example of the record parameter, don't think that makes sense adding it anywhere else.