Change API description to a valid OpenAPI spec

* Add missing responses (doesn't include all possible responses yet)
* Refactor invalid multi in body parameters into a single parameter
* Change form type into valid formData
* Fix use of required fields
* Apply a few other minor fixes

docs/rest-api.yml

@@ -1,4 +1,4 @@
-# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default
+# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default
 swagger: '2.0'
 info:
   title: JupyterHub
@@ -7,7 +7,7 @@ info:
   license:
     name: BSD-3-Clause
 schemes:
-  - [http, https]
+  [http, https]
 securityDefinitions:
   token:
     type: apiKey
@@ -190,7 +190,7 @@ paths:
           in: path
           required: true
           type: string
-        - body:
+        - name: body
           in: body
           schema:
             type: object
@@ -202,22 +202,21 @@ paths:
                   Timestamp of last-seen activity for this user.
                   Only needed if this is not activity associated
                   with using a given server.
-                required: false
               servers:
                 description: |
                   Register activity for specific servers by name.
                   The keys of this dict are the names of servers.
                   The default server has an empty name ('').
-                required: false
                 type: object
                 properties:
                   '<server name>':
                     description: |
                       Activity for a single server.
                     type: object
+                    required:
+                      - last_activity
                     properties:
                       last_activity:
-                        required: true
                         type: string
                         format: date-time
                         description: |
@@ -229,7 +228,11 @@ paths:
                   last_activity: '2019-02-06T12:54:14Z'
                 gpu:
                   last_activity: '2019-02-06T12:54:14Z'
-
+      responses:
+        '401':
+          $ref: '#/responses/Unauthorized'
+        '404':
+          description: No such user
   /users/{name}/server:
     post:
       summary: Start a user's single-user notebook server
@@ -239,7 +242,7 @@ paths:
           in: path
           required: true
           type: string
-        - options:
+        - name: options
           description: |
             Spawn options can be passed as a JSON body
             when spawning via the API instead of spawn form.
@@ -247,6 +250,7 @@ paths:
             will depend on the Spawner's configuration.
           in: body
           required: false
+          schema:
             type: object
       responses:
         '201':
@@ -280,7 +284,7 @@ paths:
           in: path
           required: true
           type: string
-        - options:
+        - name: options
           description: |
             Spawn options can be passed as a JSON body
             when spawning via the API instead of spawn form.
@@ -288,6 +292,7 @@ paths:
             will depend on the Spawner's configuration.
           in: body
           required: false
+          schema:
             type: object
       responses:
         '201':
@@ -313,6 +318,7 @@ paths:
             Removing a server deletes things like the state of the stopped server.
           in: body
           required: false
+          schema:
             type: boolean
       responses:
         '204':
@@ -320,6 +326,12 @@ paths:
         '202':
           description: The user's notebook named-server has not yet stopped as it is taking a while to stop
   /users/{name}/tokens:
+    parameters:
+      - name: name
+        description: username
+        in: path
+        required: true
+        type: string
     get:
       summary: List tokens for the user
       responses:
@@ -329,25 +341,43 @@ paths:
             type: array
             items:
               $ref: '#/definitions/Token'
+        '401':
+          $ref: '#/responses/Unauthorized'
+        '404':
+          description: No such user
     post:
       summary: Create a new token for the user
       parameters:
-        - name: expires_in
+        - name: token_params
+          in: body
+          required: false
+          schema:
+            type: object
+            properties:
+              expires_in:
                 type: number
-          required: false
-          in: body
                 description: lifetime (in seconds) after which the requested token will expire.
-        - name: note
+              note:
                 type: string
-          required: false
-          in: body
                 description: A note attached to the token for future bookkeeping
       responses:
         '201':
           description: The newly created token
           schema:
             $ref: '#/definitions/Token'
+        '400':
+          description: Body must be a JSON dict or empty
   /users/{name}/tokens/{token_id}:
+    parameters:
+      - name: name
+        description: username
+        in: path
+        required: true
+        type: string
+      - name: token_id
+        in: path
+        required: true
+        type: string
     get:
       summary: Get the model for a token by id
       responses:
@@ -361,12 +391,13 @@ paths:
         '204':
           description: The token has been deleted
   /user:
+    get:
       summary: Return authenticated user's model
-    description:
-    parameters:
       responses:
         '200':
           description: The authenticated user's model is returned.
+          schema:
+            $ref: '#/definitions/User'
   /groups:
     get:
       summary: List groups
@@ -539,13 +570,14 @@ paths:
         Logging in via this method is only available when the active Authenticator
         accepts passwords (e.g. not OAuth).
       parameters:
-        - name: username
+        - name: credentials
           in: body
-          required: false
+          schema:
+            type: object
+            properties:
+              username:
                 type: string
-        - name: password
+              password:
-          in: body
-          required: false
                 type: string
       responses:
         '200':
@@ -618,6 +650,11 @@ paths:
           in: query
           required: true
           type: string
+      responses:
+        '200':
+          description: Success
+        '400':
+          description: OAuth2Error
   /oauth2/token:
     post:
       summary: Request an OAuth2 token
@@ -629,27 +666,27 @@ paths:
       parameters:
         - name: client_id
           description: The client id
-          in: form
+          in: formData
           required: true
           type: string
         - name: client_secret
           description: The client secret
-          in: form
+          in: formData
           required: true
           type: string
         - name: grant_type
           description: The grant type (always 'authorization_code')
-          in: form
+          in: formData
           required: true
           type: string
         - name: code
           description: The code provided by the authorization redirect
-          in: form
+          in: formData
           required: true
           type: string
         - name: redirect_uri
           description: The redirect url
-          in: form
+          in: formData
           required: true
           type: string
       responses:
@@ -668,14 +705,28 @@ paths:
     post:
       summary: Shutdown the Hub
       parameters:
-        - name: proxy
+        - name: body
           in: body
+          schema:
+            type: object
+            properties:
+              proxy:
                 type: boolean
                 description: Whether the proxy should be shutdown as well (default from Hub config)
-        - name: servers
+              servers:
-          in: body
                 type: boolean
                 description: Whether users' notebook servers should be shutdown as well (default from Hub config)
+      responses:
+        '202':
+          description: Shutdown successful
+        '400':
+          description: Unexpeced value for proxy or servers
+# Descriptions of common responses
+responses:
+  NotFound:
+    description: The specified resource was not found
+  Unauthorized:
+    description: Authentication/Authorization error
 definitions:
   User:
     type: object
@@ -703,10 +754,9 @@ definitions:
         format: date-time
         description: Timestamp of last-seen activity from the user
       servers:
-        type: object
+        type: array
         description: The active servers for this user.
         items:
-          schema:
           $ref: '#/definitions/Server'
   Server:
     type: object