Added swagger doc for GIG DNS API

[QiluXie]

Problem

We are working with GIG from ITSM to explore the possibility of automatically updating DNS records for agency domains as part of the future site launch process.

As the first step, we are requested to create a swagger API spec to show how the API endpoints could look like before GIG can implement them.

Closes IS-611

Solution

This PR added a swagger file under docs folder.
To view the API specs on Swagger UI, use one of the two methods:

• View it on the public link from Swagger Hub
• Download the file and load it directly to swagger editor

Breaking Changes

• Yes - this PR contains breaking changes
  • Details ...
• No - this PR is backwards compatible with ALL of the following feature flags in this doc

[kishore03109]

Hey! I think a quick win here is make 1 api request pre zone record changed. That would mean for cleaner design as now we dont have to have an entire 4xx error when any one of the requests fail.

I think we could just closely model https://developers.cloudflare.com/api/operations/zones-post here!

The folks did email us, but am worried that flow is really too complicated and conflates business logic within the restful API designs :/ We can discuss this offline

[QiluXie]

Hey! I think a quick win here is make 1 api request pre zone record changed. That would mean for cleaner design as now we dont have to have an entire 4xx error when any one of the requests fail.

I think we could just closely model https://developers.cloudflare.com/api/operations/zones-post here!

The folks did email us, but am worried that flow is really too complicated and conflates business logic within the restful API designs :/ We can discuss this offline

Hey, sorry, didn't quite get this, why do we want to model cloudflare API to create zone in our case?

[kishore03109]

Mostly ok, areas for improvement:

1. Dont understand the priority for the 200 returns, was this intentional?
2. Could we add a success key in the JSON object?

Concretely, would rather the shape of the return objects to be of:
for

{
"type": "A",
"name": "string",
"content": "string",
"success": true
}

and
{
"type": "A",
"name": "string",
"content": "string",
"success": false
"error": object
}

That way we can expect a similar shape for the return values, agnostic of the success/failure of the operation

[QiluXie]

Mostly ok, areas for improvement:

1. Dont understand the priority for the 200 returns, was this intentional?
2. Could we add a success key in the JSON object?

Concretely, would rather the shape of the return objects to be of: for

{ "type": "A", "name": "string", "content": "string", "success": true }

and { "type": "A", "name": "string", "content": "string", "success": false "error": object }

That way we can expect a similar shape for the return values, agnostic of the success/failure of the operation

Hey, thanks for the comment.

1. For the priority, if you look at the DNSRecord schema (line 174), you will find it's an optional field under DNSRecord which only applies to MX and SRV records. You can find it on the Cloudflare API doc by selecting MX record for the request body. In this swagger file, it's displaying an example response of the GET DNS records call, therefore it displays all possible optional fields in the schema.
2. Hmm, I think you might misread the doc on the mentioned response body, it only happens in the GET call which lists the existing DNS records for a given name. Hence there is no failure case in the response for each record. For POST and DELETE call, we do have a 201 and 200 responses indicating the success of the operation and other responses (4xx or 5xx) indicating the failure of it.

Let me know if you want to clarify them over a quick call. Thanks!

[QiluXie]

@kishore03109 as discussed, added 401 error response for 3 API calls in ce641d3