mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-18 15:33:02 +00:00
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
This commit is contained in:
Sören Brunk
@@ -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
|
||||
in: body
|
||||
required: false
|
||||
password:
|
||||
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
|
||||
in: body
|
||||
servers:
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user