upd: improve user api (#878)

powerdnsadmin/swagger-spec.yaml

@@ -1,6 +1,6 @@
 swagger: '2.0'
 info:
-  version: "0.0.13"
+  version: "0.0.14"
   title: PowerDNS Admin Authoritative HTTP API
   license:
     name: MIT
@@ -1041,6 +1041,10 @@ paths:
           description: Unprocessable Entry, the User data provided has issues
           schema:
             $ref: '#/definitions/Error'
+        '409':
+          description: Duplicate Entry, either the Name or the Email is already in use
+          schema:
+            $ref: '#/definitions/Error'
         '500':
           description: Internal Server Error. There was a problem creating the user
           schema:
@@ -1063,7 +1067,7 @@ paths:
         '200':
           description: Retrieve a specific User
           schema:
-            $ref: '#/definitions/User'
+            $ref: '#/definitions/UserDetailed'
         '404':
           description: Not found. The User with the specified username does not exist
           schema:
@@ -1206,6 +1210,10 @@ paths:
           description: Unprocessable Entry, the Account data provided has issues.
           schema:
             $ref: '#/definitions/Error'
+        '409':
+          description: Duplicate Entry, the Name is already in use
+          schema:
+            $ref: '#/definitions/Error'
         '500':
           description: Internal Server Error. There was a problem creating the account
           schema:
@@ -1299,7 +1307,7 @@ paths:
           description: Internal Server Error. Contains error message
           schema:
             $ref: '#/definitions/Error'
-  '/pdnsadmin/accounts/users/{account_id}':
+  '/pdnsadmin/accounts/{account_id}/users':
     parameters:
       - name: account_id
         type: integer
@@ -1316,7 +1324,7 @@ paths:
         - user
       responses:
         '200':
-          description: List of User objects
+          description: List of Summarized User objects
           schema:
             type: array
             items:
@@ -1329,7 +1337,7 @@ paths:
           description: Internal Server Error, accounts could not be retrieved. Contains error message
           schema:
             $ref: '#/definitions/Error'
-  '/pdnsadmin/accounts/users/{account_id}/{user_id}':
+  '/pdnsadmin/accounts/{account_id}/users/{user_id}':
     parameters:
       - name: account_id
         type: integer
@@ -1380,7 +1388,6 @@ paths:
           schema:
             $ref: '#/definitions/Error'
 
-
 definitions:
   Server:
     title: Server
@@ -1603,9 +1610,9 @@ definitions:
           type: string
           description: 'Name of the zone'
 
-  PDNSAdminApiKeyRole:
-    title: PDNSAdminApiKeyRole
-    description: Role of ApiKey, defines privileges on domains
+  PDNSAdminRole:
+    title: PDNSAdminRole
+    description: Roles of PowerDNS Admin
     properties:
       id:
         type: integer
@@ -1613,7 +1620,7 @@ definitions:
         readOnly: true
       name:
         type: string
-        description: 'Name of role'
+        description: 'The Name of PDNSAdmin role'
 
   ApiKey:
     title: ApiKey
@@ -1630,12 +1637,10 @@ definitions:
         type: string
         description: 'not used on POST, POSTing to server generates the key material'
       domains:
-        type: array
-        items:
-          $ref: '#/definitions/PDNSAdminZones'
+        $ref: '#/definitions/PDNSAdminZones'
         description: 'domains to which this apikey has access'
       role:
-        $ref: '#/definitions/PDNSAdminApiKeyRole'
+        $ref: '#/definitions/PDNSAdminRole'
       description:
         type: string
         description: 'Some user defined description'
@@ -1676,10 +1681,51 @@ definitions:
         type: boolean
         description: The confirmed status
         readOnly: false
-      role_id:
+      role:
+        $ref: '#/definitions/PDNSAdminRole'
+
+  UserDetailed:
+    title: User
+    description: User that can access the gui/api
+    properties:
+      id:
         type: integer
-        description: The ID of the role
+        description: The ID for this user (unique)
+        readOnly: true
+      username:
+        type: string
+        description: The username for this user (unique, immutable)
         readOnly: false
+      password:
+        type: string
+        description: The hashed password for this user
+        readOnly: false
+      firstname:
+        type: string
+        description: The firstname of this user
+        readOnly: false
+      lastname:
+        type: string
+        description: The lastname of this user
+        readOnly: false
+      email:
+        type: string
+        description: Email addres for this user
+        readOnly: false
+      otp_secret:
+        type: string
+        description: OTP secret
+        readOnly: false
+      confirmed:
+        type: boolean
+        description: The confirmed status
+        readOnly: false
+      role:
+        $ref: '#/definitions/PDNSAdminRole'
+      accounts:
+        type: array
+        items:
+          $ref: '#/definitions/AccountSummary'
 
   Account:
     title: Account
@@ -1706,6 +1752,19 @@ definitions:
         description: The email address of the contact for this account
         readOnly: false
 
+  AccountSummary:
+    title: AccountSummry
+    description: Summary of an Account that 'owns' zones
+    properties:
+      id:
+        type: integer
+        description: The ID for this account (unique)
+        readOnly: true
+      name:
+        type: string
+        description: The name for this account (unique, immutable)
+        readOnly: false
+
   ConfigSetting:
     title: ConfigSetting
     properties: