Merge ~jsseidel/maas:jsseidel-dnsresources-api-annotations into maas:master

[Spencer Seidel]

Added API annotations and examples for dnsresources and dnsresourcerecords.

[Newell Jensen (newell-jensen)]

Looks good.

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b jsseidel-dnsresources-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 01d55d6f219f2b060b0d776b02f2ac2f6c1810a7

review: Approve

[MAAS Lander (maas-lander)]

LANDING
-b jsseidel-dnsresources-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED MERGE
LOG: http://maas-ci-jenkins.internal:8080/job/maas/job/branch-lander/341301/console

diff --git a/src/maasserver/api/dnsresourcerecords.py b/src/maasserver/api/dnsresourcerecords.py
index 992a580..5a74342 100644
--- a/src/maasserver/api/dnsresourcerecords.py
+++ b/src/maasserver/api/dnsresourcerecords.py
@@ -43,12 +43,23 @@ class DNSResourceRecordsHandler(OperationsHandler):
         return ('dnsresourcerecords_handler', [])
 
     def read(self, request):
-        """List all dnsresourcerecords.
+        """@description-title List all DNS resource records
+        @description List all DNS resource records.
 
-        :param domain: restrict the listing to entries for the domain.
-        :param name: restrict the listing to entries of the given name.
-        :param rrtype: restrict the listing to entries which have
-            records of the given rrtype.
+        @param (string) "domain" [required=false] Restricts the listing to
+        entries for the domain.
+
+        @param (string) "name" [required=false] Restricts the listing to
+        entries of the given name.
+
+        @param (string) "rrtype" [required=false] Restricts the listing to
+        entries which have records of the given rrtype.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing a list of the
+        requested DNS resource record objects.
+        @success-example "success-json" [exkey=dnsresourcerecords-read]
+        placeholder text
         """
         data = request.GET
         fqdn = data.get('fqdn', None)
@@ -82,19 +93,31 @@ class DNSResourceRecordsHandler(OperationsHandler):
 
     @admin_method
     def create(self, request):
-        """Create a DNS resource record.
-
-        :param fqdn: Hostname (with domain) for the dnsresource.  Either fqdn
-            or (name, domain) must be specified.  Fqdn is ignored if either
-            name or domain is given (e.g. www.your-maas.maas).
-        :param name: The name (or hostname without a domain) of the DNS
-            resource record (e.g. www.your-maas)
-        :param domain: The domain (name or id) where to create the DNS
-            resource record (Domain (e.g. 'maas')
-        :param rrtype: The resource record type (e.g 'cname', 'mx', 'ns',
-            'srv', 'sshfp', 'txt')
-        :param rrdata: The resource record data (e.g. 'your-maas',
-            '10 mail.your-maas.maas')
+        """@description-title Create a DNS resource record
+        @description Create a new DNS resource record.
+
+        @param (string) "fqdn" [required=false] Hostname (with domain) for the
+        dnsresource.  Either ``fqdn`` or ``name`` and  ``domain`` must be
+        specified.  ``fqdn`` is ignored if either name or domain is given (e.g.
+        www.your-maas.maas).
+
+        @param (string) "name" [required=false] The name (or hostname without a
+        domain) of the DNS resource record (e.g. www.your-maas)
+
+        @param (string) "domain" [required=false] The domain (name or id) where
+        to create the DNS resource record (Domain (e.g. 'maas')
+
+        @param (string) "rrtype" [required=false] The resource record type (e.g
+        ``cname``, ``mx``, ``ns``, ``srv``, ``sshfp``, ``txt``).
+
+        @param (string) "rrdata" [required=false] The resource record data
+        (e.g. 'your-maas', '10 mail.your-maas.maas')
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the new DNS
+        resource record object.
+        @success-example "success-json" [exkey=dnsresourcerecords-create]
+        placeholder text
         """
         data = request.data.copy()
         domain = None
@@ -167,22 +190,52 @@ class DNSResourceRecordHandler(OperationsHandler):
         return dnsresourcerecord.fqdn()
 
     def read(self, request, id):
-        """Read dnsresourcerecord.
+        """@description-title Read a DNS resource record
+        description Read a DNS resource record with the given id.
 
-        Returns 404 if the dnsresourcerecord is not found.
+        @param (int) "{id}" [required=true] The DNS resource record id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the requested
+        DNS resource object.
+        @success-example "success-json" [exkey=dnsresourcerecords-read-by-id]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource record was not
+        found.
+        @error-example "not-found"
+            Not Found
         """
         return DNSData.objects.get_dnsdata_or_404(
             id, request.user, NodePermission.view)
 
     def update(self, request, id):
-        """Update dnsresourcerecord.
+        """@description-title Update a DNS resource record
+        @description Update a DNS resource record with the given id.
+
+        @param (int) "{id}" [required=true] The DNS resource record id.
+
+        @param (string) "rrtype" [required=false] Resource type.
+
+        @param (string) "rrdata" [required=false] Resource data (everything to
+        the right of type.)
 
-        :param rrtype: Resource Type
-        :param rrdata: Resource Data (everything to the right of Type.)
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated DNS
+        resource record object.
+        @success-example "success-json" [exkey=dnsresourcerecords-update]
+        placeholder text
 
-        Returns 403 if the user does not have permission to update the
-        dnsresourcerecord.
-        Returns 404 if the dnsresourcerecord is not found.
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permission to update
+        the requested DNS resource record.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource record is not
+        found.
+        @error-example "not-found"
+            Not Found
         """
         dnsdata = DNSData.objects.get_dnsdata_or_404(
             id, request.user, NodePermission.admin)
@@ -195,11 +248,22 @@ class DNSResourceRecordHandler(OperationsHandler):
             raise MAASAPIValidationError(form.errors)
 
     def delete(self, request, id):
-        """Delete dnsresourcerecord.
+        """@description-title Delete a DNS resource record
+        @description Delete a DNS resource record with the given id.
+
+        @param (int) "{id}" [required=true] The DNS resource record id.
+
+        @success (http-status-code) "server-success" 204
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permission to delete
+        the requested DNS resource record.
 
-        Returns 403 if the user does not have permission to delete the
-        dnsresourcerecord.
-        Returns 404 if the dnsresourcerecord is not found.
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource record is not
+        found.
+        @error-example "not-found"
+            Not Found
         """
         dnsdata = DNSData.objects.get_dnsdata_or_404(
             id, request.user, NodePermission.admin)
diff --git a/src/maasserver/api/dnsresources.py b/src/maasserver/api/dnsresources.py
index 68babe7..28a1027 100644
--- a/src/maasserver/api/dnsresources.py
+++ b/src/maasserver/api/dnsresources.py
@@ -123,14 +123,31 @@ class DNSResourcesHandler(OperationsHandler):
         return ('dnsresources_handler', [])
 
     def read(self, request):
-        """List all resources for the specified criteria.
-
-        :param domain: restrict the listing to entries for the domain.
-        :param name: restrict the listing to entries of the given name.
-        :param rrtype: restrict the listing to entries which have
-            records of the given rrtype.
-        :param all: if True, also include implicit DNS records created for
-            nodes registered in MAAS.
+        """@description-title List resources
+        @description List all resources for the specified criteria.
+
+        @param (string) "domain" [required=false] Restricts the listing to
+        entries for the domain.
+
+        @param (string) "name" [required=false] Restricts the listing to
+        entries of the given name.
+
+        @param (string) "rrtype" [required=false] Restricts the listing to
+        entries which have records of the given rrtype.
+
+        @param (boolean) "all" [required=false] Include implicit DNS records
+        created for nodes registered in MAAS if true.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing a list of the
+        requested DNS resource objects.
+        @success-example "success-json" [exkey=dnsresources-read] placeholder
+        text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resources are not found.
+        @error-example "not-found"
+            Not Found
         """
         data = request.GET
         fqdn = data.get('fqdn', None)
@@ -151,16 +168,29 @@ class DNSResourcesHandler(OperationsHandler):
 
     @admin_method
     def create(self, request):
-        """Create a dnsresource.
-
-        :param fqdn: Hostname (with domain) for the dnsresource.  Either fqdn
-            or (name, domain) must be specified.  Fqdn is ignored if either
-            name or domain is given.
-        :param name: Hostname (without domain)
-        :param domain: Domain (name or id)
-        :param address_ttl: Default ttl for entries in this zone.
-        :param ip_addresses: (optional) Address (ip or id) to assign to the
-            dnsresource.
+        """@description-title Create a DNS resource
+        @description Create a DNS resource.
+
+        @param (string) "fqdn" [required=false] Hostname (with domain) for the
+        dnsresource.  Either ``fqdn`` or ``name`` and ``domain`` must be
+        specified.  ``fqdn`` is ignored if either ``name`` or ``domain`` is
+        given.
+
+        @param (string) "name" [required=true] Hostname (without domain).
+
+        @param (string) "domain" [required=true] Domain (name or id).
+
+        @param (string) "address_ttl" [required=false] Default TTL for entries
+        in this zone.
+
+        @param (string) "ip_addresses" [required=false] Address (ip or id) to
+        assign to the dnsresource.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the new DNS
+        resource object.
+        @success-example "success-json" [exkey=dnsresources-create] placeholder
+        text
         """
         data = request.data.copy()
         fqdn = data.get('fqdn', None)
@@ -232,22 +262,51 @@ class DNSResourceHandler(OperationsHandler):
             return dnsresource.dnsdata_set.all().order_by('rrtype')
 
     def read(self, request, id):
-        """Read dnsresource.
+        """@description-title Read a DNS resource
+        @description Read a DNS resource by id.
 
-        Returns 404 if the dnsresource is not found.
+        @param (int) "{id}" [required=true] The DNS resource id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the requested
+        DNS resource object.
+        @success-example "success-json" [exkey=dnsresources-read-by-id]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource is not found.
+        @error-example "not-found"
+            Not Found
         """
         return DNSResource.objects.get_dnsresource_or_404(
             id, request.user, NodePermission.view)
 
     def update(self, request, id):
-        """Update dnsresource.
+        """@description-title Update a DNS resource
+        @description Update a DNS resource with the given id.
+
+        @param (int) "{id}" [required=true] The DNS resource id.
 
-        :param fqdn: Hostname (with domain) for the dnsresource.
-        :param ip_address: Address to assign to the dnsresource.
+        @param (string) "fqdn" [required=false] Hostname (with domain) for the
+        dnsresource.
 
-        Returns 403 if the user does not have permission to update the
+        @param (string) "ip_address" [required=false] Address to assign to the
         dnsresource.
-        Returns 404 if the dnsresource is not found.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated DNS
+        resource object.
+        @success-example "success-json" [exkey=dnsresources-update] placeholder
+        text
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permission to update
+        the requested DNS resource.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource is not found.
+        @error-example "not-found"
+            Not Found
         """
         dnsresource = DNSResource.objects.get_dnsresource_or_404(
             id, request.user, NodePermission.admin)
@@ -259,11 +318,21 @@ class DNSResourceHandler(OperationsHandler):
             raise MAASAPIValidationError(form.errors)
 
     def delete(self, request, id):
-        """Delete dnsresource.
+        """@description-title Delete a DNS resource
+        @description Delete a DNS resource with the given id.
 
-        Returns 403 if the user does not have permission to delete the
-        dnsresource.
-        Returns 404 if the dnsresource is not found.
+        @param (int) "{id}" [required=true] The DNS resource id.
+
+        @success (http-status-code) "server-success" 204
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permission to update
+        the requested DNS resource.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested DNS resource is not found.
+        @error-example "not-found"
+            Not Found
         """
         dnsresource = DNSResource.objects.get_dnsresource_or_404(
             id, request.user, NodePermission.admin)
diff --git a/src/maasserver/api/examples/dnsresourcerecords.json b/src/maasserver/api/examples/dnsresourcerecords.json
new file mode 100644
index 0000000..78dca29
--- /dev/null
+++ b/src/maasserver/api/examples/dnsresourcerecords.json
@@ -0,0 +1,36 @@
+{
+  "dnsresourcerecords-read": [
+    {
+      "ttl": null,
+      "rrtype": "CNAME",
+      "rrdata": "172.16.0.0",
+      "fqdn": "sample-machine-new.ubnt",
+      "id": 1,
+      "resource_uri": "/MAAS/api/2.0/dnsresourcerecords/1/"
+    }
+  ],
+  "dnsresourcerecords-create": {
+    "ttl": null,
+    "rrtype": "TXT",
+    "rrdata": "172.16.0.0",
+    "fqdn": "sample-machine-new.ubnt",
+    "id": 1,
+    "resource_uri": "/MAAS/api/2.0/dnsresourcerecords/1/"
+  },
+  "dnsresourcerecords-read-by-id": {
+    "ttl": null,
+    "rrtype": "CNAME",
+    "rrdata": "172.16.0.0",
+    "fqdn": "sample-machine-new.ubnt",
+    "id": 1,
+    "resource_uri": "/MAAS/api/2.0/dnsresourcerecords/1/"
+  },
+  "dnsresourcerecords-update": {
+    "ttl": null,
+    "rrtype": "TXT",
+    "rrdata": "172.16.0.0",
+    "fqdn": "sample-machine-new.ubnt",
+    "id": 1,
+    "resource_uri": "/MAAS/api/2.0/dnsresourcerecords/1/"
+  }
+}
diff --git a/src/maasserver/api/examples/dnsresources.json b/src/maasserver/api/examples/dnsresources.json
new file mode 100644
index 0000000..4818bb4
--- /dev/null
+++ b/src/maasserver/api/examples/dnsresources.json
@@ -0,0 +1,47 @@
+{
+  "dnsresources-read": [
+    {
+      "address_ttl": null,
+      "id": -1,
+      "ip_addresses": null,
+      "resource_records": [
+        {
+          "system_id": "ydpcwh",
+          "node_type": 0,
+          "user_id": null,
+          "dnsresource_id": null,
+          "ttl": null,
+          "rrtype": "A",
+          "rrdata": "172.16.2.111",
+          "dnsdata_id": null
+        }
+      ],
+      "fqdn": "divine-buck.ubnt",
+      "resource_uri": "/MAAS/api/2.0/dnsresources/-1/"
+    }
+  ],
+  "dnsresources-create": {
+    "address_ttl": null,
+    "fqdn": "sample-machine.ubnt",
+    "resource_records": [],
+    "id": 1,
+    "ip_addresses": [],
+    "resource_uri": "/MAAS/api/2.0/dnsresources/1/"
+  },
+  "dnsresources-read-by-id": {
+    "address_ttl": null,
+    "fqdn": "sample-machine.ubnt",
+    "resource_records": [],
+    "ip_addresses": [],
+    "id": 1,
+    "resource_uri": "/MAAS/api/2.0/dnsresources/1/"
+  },
+  "dnsresources-update": {
+    "address_ttl": null,
+    "fqdn": "sample-machine.ubnt",
+    "resource_records": [],
+    "ip_addresses": [],
+    "id": 1,
+    "resource_uri": "/MAAS/api/2.0/dnsresources/1/"
+  }
+}