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

[Spencer Seidel]

Added API annotations for ssl_keys and examples. Also added missing success status codes to ssh_keys.

[Newell Jensen (newell-jensen)]

Looks good.

review: Approve

diff --git a/src/maasserver/api/examples/account.json b/src/maasserver/api/examples/account.json
index 67ac321..9b95c6a 100644
--- a/src/maasserver/api/examples/account.json
+++ b/src/maasserver/api/examples/account.json
@@ -37,5 +37,20 @@
     "id": 11,
     "keysource": "lp:user",
     "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/11/"
+  },
+  "ssl-keys-list": [
+    {
+      "key": "-----BEGIN CERTIFICATE-----\r\nMIIDYDCCAkigAwIBAgIJANv2xTlvnerlMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\r\nBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX\r\naWRnaXRzIFB0eSBMdGQwHhcNMTgxMTIxMjMxNjUwWhcNMjgxMTE4MjMxNjUwWjBF\r\nMQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50\r\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\r\nCgKCAQEAqD8WoD9CWZ6gpwN7nGZfWjVMYRs2Mv+aaureSQudpE53XOGTrMBBxon2\r\nJNp6a1BwpOIl1sbTsYPDyOVhZZ4vRdHQ2pGSW8b4eKQqaB8Ae9w55gMxvUgK1e6t\r\nIe8Quhb7bs2UsaG/6vDRJetmSiX6ASjcBNG/0X6IJGsw0J5m+sgKLJwb49ZU72eZ\r\nGNwV1nJcz741AMpKU4apeafmSYQSfie+kSP9uDqekNzSDx615+HrClSdGwwya1P/\r\nE6Xb3WvgRnh30HJpZG61E6+vUfYYJtowLaj0gaWY6ohjkVHmgfIvHTVI7p7d0jZ4\r\nZvZgw2nWDSm/qV/Cl2embYWVUyctaQIDAQABo1MwUTAdBgNVHQ4EFgQUmZyWKIt8\r\nlUJUBj7f8kiOEs/Xih8wHwYDVR0jBBgwFoAUmZyWKIt8lUJUBj7f8kiOEs/Xih8w\r\nDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAje7KLWW/tf2tx2/g\r\nXmkltSQLfhL+mTVCUm3LaxDrDR5Iw0igngBekxACyqy20OyVl26bybYxAAGIZC+s\r\nax24ARKizUhd/FTFya7Xc4bEvWOcytcODUOBCuAmbRn/saeGVC+b81OjF+ndkXso\r\nweQ7YADaZQQD8ZkaPCzz8jQBe4AL48lA7TovHDDk68XDgYkcyArvGsQpo1527NYZ\r\nngMT9th7eWeHD+AAo9LGE9D4+6FoPo0Wloq9pCarM7q53Vp7pEOwar8Z3N9+Wms3\r\nrw4e59fnqslCXdztMO7Y4VTsyRUR6c9tEou560i48PXIYuGHf17ioouGg50XPT5Z\r\nFnCh/w==\r\n-----END CERTIFICATE-----",
+      "id": 1,
+      "resource_uri": "/MAAS/api/2.0/account/prefs/sslkeys/1/"
+    }
+  ],
+  "ssl-keys-create": {
+    "key": "-----BEGIN CERTIFICATE-----\r\nMIIDYDCCAkigAwIBAgIJANv2xTlvnerlMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\r\nBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX\r\naWRnaXRzIFB0eSBMdGQwHhcNMTgxMTIxMjMxNjUwWhcNMjgxMTE4MjMxNjUwWjBF\r\nMQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50\r\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\r\nCgKCAQEAqD8WoD9CWZ6gpwN7nGZfWjVMYRs2Mv+aaureSQudpE53XOGTrMBBxon2\r\nJNp6a1BwpOIl1sbTsYPDyOVhZZ4vRdHQ2pGSW8b4eKQqaB8Ae9w55gMxvUgK1e6t\r\nIe8Quhb7bs2UsaG/6vDRJetmSiX6ASjcBNG/0X6IJGsw0J5m+sgKLJwb49ZU72eZ\r\nGNwV1nJcz741AMpKU4apeafmSYQSfie+kSP9uDqekNzSDx615+HrClSdGwwya1P/\r\nE6Xb3WvgRnh30HJpZG61E6+vUfYYJtowLaj0gaWY6ohjkVHmgfIvHTVI7p7d0jZ4\r\nZvZgw2nWDSm/qV/Cl2embYWVUyctaQIDAQABo1MwUTAdBgNVHQ4EFgQUmZyWKIt8\r\nlUJUBj7f8kiOEs/Xih8wHwYDVR0jBBgwFoAUmZyWKIt8lUJUBj7f8kiOEs/Xih8w\r\nDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAje7KLWW/tf2tx2/g\r\nXmkltSQLfhL+mTVCUm3LaxDrDR5Iw0igngBekxACyqy20OyVl26bybYxAAGIZC+s\r\nax24ARKizUhd/FTFya7Xc4bEvWOcytcODUOBCuAmbRn/saeGVC+b81OjF+ndkXso\r\nweQ7YADaZQQD8ZkaPCzz8jQBe4AL48lA7TovHDDk68XDgYkcyArvGsQpo1527NYZ\r\nngMT9th7eWeHD+AAo9LGE9D4+6FoPo0Wloq9pCarM7q53Vp7pEOwar8Z3N9+Wms3\r\nrw4e59fnqslCXdztMO7Y4VTsyRUR6c9tEou560i48PXIYuGHf18ioouGg50XPT5Z\r\nFnCh/w==\r\n-----END CERTIFICATE-----",
+    "id": 2
+  },
+  "ssl-keys-get": {
+    "key": "-----BEGIN CERTIFICATE-----\r\nMIIDYDCCAkigAwIBAgIJANv2xTlvnerlMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\r\nBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX\r\naWRnaXRzIFB0eSBMdGQwHhcNMTgxMTIxMjMxNjUwWhcNMjgxMTE4MjMxNjUwWjBF\r\nMQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50\r\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\r\nCgKCAQEAqD8WoD9CWZ6gpwN7nGZfWjVMYRs2Mv+aaureSQudpE53XOGTrMBBxon2\r\nJNp6a1BwpOIl1sbTsYPDyOVhZZ4vRdHQ2pGSW8b4eKQqaB8Ae9w55gMxvUgK1e6t\r\nIe8Quhb7bs2UsaG/6vDRJetmSiX6ASjcBNG/0X6IJGsw0J5m+sgKLJwb49ZU72eZ\r\nGNwV1nJcz741AMpKU4apeafmSYQSfie+kSP9uDqekNzSDx615+HrClSdGwwya1P/\r\nE6Xb3WvgRnh30HJpZG61E6+vUfYYJtowLaj0gaWY6ohjkVHmgfIvHTVI7p7d0jZ4\r\nZvZgw2nWDSm/qV/Cl2embYWVUyctaQIDAQABo1MwUTAdBgNVHQ4EFgQUmZyWKIt8\r\nlUJUBj7f8kiOEs/Xih8wHwYDVR0jBBgwFoAUmZyWKIt8lUJUBj7f8kiOEs/Xih8w\r\nDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAje7KLWW/tf2tx2/g\r\nXmkltSQLfhL+mTVCUm3LaxDrDR5Iw0igngBekxACyqy20OyVl26bybYxAAGIZC+s\r\nax24ARKizUhd/FTFya7Xc4bEvWOcytcODUOBCuAmbRn/saeGVC+b81OjF+ndkXso\r\nweQ7YADaZQQD8ZkaPCzz8jQBe4AL48lA7TovHDDk68XDgYkcyArvGsQpo1527NYZ\r\nngMT9th7eWeHD+AAo9LGE9D4+6FoPo0Wloq9pCarM7q53Vp7pEOwar8Z3N9+Wms3\r\nrw4e59fnqslCXdztMO7Y4VTsyRUR6c9tEou560i48PXIYuGHf18ioouGg50XPT5Z\r\nFnCh/w==\r\n-----END CERTIFICATE-----",
+    "id": 2
   }
 }
diff --git a/src/maasserver/api/ssh_keys.py b/src/maasserver/api/ssh_keys.py
index eda9c17..58d29be 100644
--- a/src/maasserver/api/ssh_keys.py
+++ b/src/maasserver/api/ssh_keys.py
@@ -180,6 +180,12 @@ class SSHKeyHandler(OperationsHandler):
 
         @param (int) "id" [required=true] An SSH key ID.
 
+        @success (http-status-code) "200" 200
+        @success (json) "success-json" A JSON object containing a list of
+        imported keys.
+        @success-example "success-json" [exkey=ssh-keys-get] placeholder
+        text
+
         @error (http-status-code) "404" 404
         @error (content) "not-found" The requested SSH key is not found.
         @error-example "not-found"
@@ -194,6 +200,8 @@ class SSHKeyHandler(OperationsHandler):
 
         @param (int) "id" [required=true] An SSH key ID.
 
+        @success (http-status-code) "204" 204
+
         @error (http-status-code) "404" 404
         @error (content) "not-found" The requested SSH key is not found.
         @error-example "not-found"
diff --git a/src/maasserver/api/ssl_keys.py b/src/maasserver/api/ssl_keys.py
index 10dcf33..1e5d0a0 100644
--- a/src/maasserver/api/ssl_keys.py
+++ b/src/maasserver/api/ssl_keys.py
@@ -38,14 +38,32 @@ class SSLKeysHandler(OperationsHandler):
     update = delete = None
 
     def read(self, request):
-        """List all keys belonging to the requesting user."""
+        """@description-title List keys
+        @description List all keys belonging to the requesting user.
+
+        @success (http-status-code) "200" 200
+        @success (json) "success-json" A JSON object containing a list of SSL
+        keys.
+        @success-example "success-json" [exkey=ssl-keys-list] placeholder text
+        """
         return SSLKey.objects.filter(user=request.user).order_by('id')
 
     def create(self, request):
-        """Add a new SSL key to the requesting user's account.
+        """@description-title Add a new SSL key
+        @description Add a new SSL key to the requesting user's account.
+
+        @param (string) "key" [required=true,formatting=true] An SSL key
+        should be provided in the request payload as form data with the name
+        'key':
+
+            key: "key data"
+
+        - ``key data``: The contents of a pem file.
 
-        The request payload should contain the SSL key data in form
-        data whose name is "key".
+        @success (http-status-code) "201" 201
+        @success (json) "success-json" A JSON object containing the new key.
+        @success-example "success-json" [exkey=ssl-keys-create] placeholder
+        text
         """
         form = SSLKeyForm(user=request.user, data=request.data)
         if form.is_valid():
@@ -65,7 +83,8 @@ class SSLKeysHandler(OperationsHandler):
 
 
 class SSLKeyHandler(OperationsHandler):
-    """Manage an SSL key.
+    """
+    Manage an SSL key.
 
     SSL keys can be retrieved or deleted.
     """
@@ -76,10 +95,26 @@ class SSLKeyHandler(OperationsHandler):
     create = update = None
 
     def read(self, request, id):
-        """GET an SSL key.
-
-        Returns 404 if the key with `id` is not found.
-        Returns 401 if the key does not belong to the requesting user.
+        """@description-title Retrieve an SSL key
+        @description Retrieves an SSL key with the given ID.
+
+        @param (int) "id" [required=true] An SSL key ID.
+
+        @success (http-status-code) "200" 200
+        @success (json) "success-json" A JSON object containing a list of
+        imported keys.
+        @success-example "success-json" [exkey=ssl-keys-get] placeholder
+        text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested SSH key is not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The requesting user does not own the key.
+        @error-example "no-perms"
+            Can't get a key you don't own.
         """
         key = get_object_or_404(SSLKey, id=id)
         if key.user != request.user:
@@ -88,10 +123,22 @@ class SSLKeyHandler(OperationsHandler):
         return key
 
     def delete(self, request, id):
-        """DELETE an SSL key.
+        """@description-title Delete an SSL key
+        @description Deletes the SSL key with the given ID.
+
+        @param (int) "id" [required=true] An SSH key ID.
+
+        @success (http-status-code) "204" 204
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested SSH key is not found.
+        @error-example "not-found"
+            Not Found
 
-        Returns 401 if the key does not belong to the requesting user.
-        Returns 204 if the key is successfully deleted.
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The requesting user does not own the key.
+        @error-example "no-perms"
+            Can't delete a key you don't own.
         """
         key = get_object_or_404(SSLKey, id=id)
         if key.user != request.user: