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

[Spencer Seidel]

Added api annotations to ssh-keys and examples.

[Newell Jensen (newell-jensen)]

Looks good. One inline suggestion.

review: Approve

[MAAS Lander (maas-lander)]

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

STATUS: SUCCESS
COMMIT: 600ee406609e549be3030e5dba6d738f2fa670f5

review: Approve

diff --git a/src/maasserver/api/examples/account.json b/src/maasserver/api/examples/account.json
new file mode 100644
index 0000000..67ac321
--- /dev/null
+++ b/src/maasserver/api/examples/account.json
@@ -0,0 +1,41 @@
+{
+  "ssh-keys-list": [
+    {
+      "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC/L1pGwyIs9mxP1MkuPVrEMfcl+qEg9wChnN/n4fGwFIJ9vXFBV8pu8rvcsigx/Ar2wZRHGIO/cwHeC+rR+jG5zw4ZyD5d+ISfVoyKsOviAQzXJTCjdx4aLItVA6LYZiv8Z3fondqpzFuVph+D/hc1sBNxlPJcFF3RJcCTf92xYyQfUlZo/RYPHzgWDYWYScoZXOxLms2ZKtyuqQFyKmlcTzlTWoYGeTtqEq5OCWG/PSlTopGqRtoZXSATAOfCDH1kyOqAtehtn6ehZ013u4Kb8d8nD66SeLOBG5xQUbm7U1LkfVLGMrXlJOhrJ58JsNTx9sq8ouNO9VknbhvWD5aH user@mymachine",
+      "id": 5,
+      "keysource": "lp:user",
+      "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/5/"
+    },
+    {
+      "key": "ssh-rsa AAAAB3NzaC1tc2EAAAADAQABAAABAQC5zQ1NvtYWGYKpLgW0QWBiGyt225JRAO9Wa9mlNG5Otq7PJ6PkIMZKrmfZnpYFoMe8gzY/FT5wqfzzKBxvHPFkSS24MIiRN6VDlE0rZJnugd2ijpmYKXwVMHFHWIbBLqES3ssO3VePF67Y4Agt7JRqDlF2C9ttQXXbu23fvccpDIzt6tPtPDJzNo3M1JexxRNMuyb0moNeHISGTTFCL8LSuVn8MvpqXLqBqR5Q0nchgym+f6nWQMknpLNA0531W/2ZOMa2h5vtWDoVPisGmOzlV41dpDOWG4wr120Yn6Q8thTh2tQbS0/UjThPnjrUjs9nJxg5X0MPkzEuoXo3KWEh user2@myothermachine",
+      "id": 6,
+      "keysource": "lp:user2",
+      "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/6/"
+    }
+  ],
+  "ssh-keys-create": {
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDRShb/bGd0DSYljfCwFI4D12wDk/qW9cSb3T++mytvfmXsisf8+ql5qEr+a0hsn6hkOMTcwdC5q/fVEo/P4KXj1DI9XEJ+j2sRj3Lw/bn+mpFmSsEUmv+PLzpQSX0JXOu2N8VjfgINJSXRrAmk6cmuc4Ro119dkYu/i7VIHiWSan0FY+P6ipaqien/m7mc1M1JhDyfO6ubQAfsP49+vqP+RmXPLhjmtf4yBVMnQavITtRctFBXf7PyvPgSrSCNS+M6+FZIjS79ctEpi8HUZDOCCZ7xS5vuJNtPcp3vwBOUNzVStBi/GzNYdbhubQnlHGzLJRBp64OWVasn/pkBfXUB",
+    "keysource": null,
+    "id": 12
+  },
+  "ssh-keys-import": [
+    {
+      "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC/L1pGwyIs9mxP1MkuPVrEMfcl+qEg9wChnN/n4fGwFIJ9vXFBV8pu8rvcsigx/Ar2wZRHGIO/cwHeC+rR+jG5zw4ZyD5d+ISfVoyKsOviAQzXJTCjdx4aLItVA6LYZiv8Z3fondqpzFuVph+D/hc1sBNxlPJcFF3RJcCTf92xYyQfUlZo/RYPHzgWDYWYScoZXOxLms2ZKtyuqQFyKmlcTzlTWoYGeTtqEq5OCWG/PSlTopGqRtoZXSATAOfCDH1kyOqAtehtn6ehZ013u4Kb8d8nD66SeLOBG5xQUbm7U1LkfVLGMrXlJOhrJ58JsNTx9sq8ouNO9VknbhvWD5aH user@mymachine",
+      "id": 5,
+      "keysource": "lp:user",
+      "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/5/"
+    },
+    {
+      "key": "ssh-rsa AAAAB3NzaC1tc2EAAAADAQABAAABAQC5zQ1NvtYWGYKpLgW0QWBiGyt225JRAO9Wa9mlNG5Otq7PJ6PkIMZKrmfZnpYFoMe8gzY/FT5wqfzzKBxvHPFkSS24MIiRN6VDlE0rZJnugd2ijpmYKXwVMHFHWIbBLqES3ssO3VePF67Y4Agt7JRqDlF2C9ttQXXbu23fvccpDIzt6tPtPDJzNo3M1JexxRNMuyb0moNeHISGTTFCL8LSuVn8MvpqXLqBqR5Q0nchgym+f6nWQMknpLNA0531W/2ZOMa2h5vtWDoVPisGmOzlV41dpDOWG4wr120Yn6Q8thTh2tQbS0/UjThPnjrUjs9nJxg5X0MPkzEuoXo3KWEh user2@myothermachine",
+      "id": 6,
+      "keysource": "lp:user2",
+      "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/6/"
+    }
+  ],
+  "ssh-keys-get": {
+    "key": "ssh-rsa AAAAB7NzaC1yc2EAAAADAQABAAABAQDhaFwhxa50r2InCHaSSCOB+PP572+Hra6CzFexUQBABJDHfcbbvFeAkjWIUIH9bAVolkHulDegc/6JbMy6p9E8TMqi4dQ1FV4VX/cFtbfJPlLVOrysTKuarRGnh0/1nKnYedfwpjF4HubuI55bgU/Strx/UYCr/WiFHSS7ExpnJJcuIwKeN1tZtVdVKy4j//EPt7GipBcAjpIB0hpFxBdxlm7GswDU+WZNEbSaNN6mkupVwkQdBdoaywlUl6iStzI7moAiIE37uSzi8xcovLBpHsfVKQyY1pSqC7E3L+qdu4MlioKiyYlsvaIk8BVj0QLGmGqvWZGUKcZF4OJxA15B jsseidel@linmbpro",
+    "id": 11,
+    "keysource": "lp:user",
+    "resource_uri": "/MAAS/api/2.0/account/prefs/sshkeys/11/"
+  }
+}
diff --git a/src/maasserver/api/ssh_keys.py b/src/maasserver/api/ssh_keys.py
index b26e157..eda9c17 100644
--- a/src/maasserver/api/ssh_keys.py
+++ b/src/maasserver/api/ssh_keys.py
@@ -55,14 +55,35 @@ class SSHKeysHandler(OperationsHandler):
     update = delete = None
 
     def read(self, request):
-        """List all keys belonging to the requesting user."""
+        """@description-title List SSH 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
+        available SSH keys.
+        @success-example "success-json" [exkey=ssh-keys-list] placeholder text
+        """
         return SSHKey.objects.filter(user=request.user)
 
     def create(self, request):
-        """Add a new SSH key to the requesting or supplied user's account.
+        """@description-title Add a new SSH key
+        @description Add a new SSH key to the requesting or supplied user's
+        account.
+
+        @param (string) "key" [required=true,formatting=true] A public SSH key
+        should be provided in the request payload as form data with the name
+        'key':
+
+            key: "key-type public-key-data"
 
-        The request payload should contain the public SSH key data in form
-        data whose name is "key".
+        - ``key-type``: ecdsa-sha2-nistp256, ecdsa-sha2-nistp384,
+          ecdsa-sha2-nistp521, ssh-dss, ssh-ed25519, ssh-rsa
+        - ``public key data``: Base64-encoded key data.
+
+        @success (http-status-code) "201" 201
+        @success (json) "success-json" A JSON object containing the new key.
+        @success-example "success-json" [exkey=ssh-keys-create] placeholder
+        text
         """
         user = request.user
         username = get_optional_param(request.POST, 'user')
@@ -94,10 +115,26 @@ class SSHKeysHandler(OperationsHandler):
 
     @operation(idempotent=False, exported_as='import')
     def import_ssh_keys(self, request):
-        """Import the requesting user's SSH keys.
+        """@description-title Import SSH keys
+        @description Import the requesting user's SSH keys for a given protocol
+        and authorization ID in protocol:auth_id format.
+
+        @param (string) "keysource" [required=true,formatting=true] The source
+        of the keys to import should be provided in the request payload as form
+        data:
+
+        E.g.
 
-        Import SSH keys for a given protocol and authorization ID in
-        protocol:auth_id format.
+            source:user
+
+        - ``source``: lp (Launchpad), gh (GitHub)
+        - ``user``: User login
+
+        @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-import] placeholder
+        text
         """
         keysource = request.data.get('keysource', None)
         if keysource is not None:
@@ -126,7 +163,8 @@ class SSHKeysHandler(OperationsHandler):
 
 
 class SSHKeyHandler(OperationsHandler):
-    """Manage an SSH key.
+    """
+    Manage an SSH key.
 
     SSH keys can be retrieved or deleted.
     """
@@ -137,18 +175,34 @@ class SSHKeyHandler(OperationsHandler):
     create = update = None
 
     def read(self, request, id):
-        """GET an SSH key.
+        """@description-title Retrieve an SSH key
+        @description Retrieves an SSH key with the given ID.
 
-        Returns 404 if the key does not exist.
+        @param (int) "id" [required=true] An SSH key ID.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested SSH key is not found.
+        @error-example "not-found"
+            Not Found
         """
         key = get_object_or_404(SSHKey, id=id)
         return key
 
     def delete(self, request, id):
-        """DELETE an SSH key.
+        """@description-title Delete an SSH key
+        @description Deletes the SSH key with the given ID.
+
+        @param (int) "id" [required=true] An SSH key ID.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested SSH key is not found.
+        @error-example "not-found"
+            Not Found
 
-        Returns 404 if the key does not exist.
-        Returns 401 if the key does not belong to the calling user.
+        @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(SSHKey, id=id)
         if key.user != request.user: