hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 15:33:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Change API description to a valid OpenAPI spec

Browse Source 
* 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
2019-05-28 18:04:17 +02:00
parent 844817297e
commit 30cfdcaa83
1 changed files with 117 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/rest-api.yml
View File

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