Skip to content

Commit 2a3498a

Browse files
jtpiojtpio
authored
Add Swagger Docs (#173)
1 parent e72a11a commit 2a3498a

File tree

17 files changed

+469
-27
lines changed

17 files changed

+469
-27
lines changed

‎.github/workflows/tests.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ jobs:
5858
- name: Run python tests
5959
# See `setup.cfg` for full test options
6060
run: |
61-
pytest
61+
pytest --pyargs jupyterlab_server
6262
- name: Upload coverage
6363
run: |
6464
codecov
@@ -77,6 +77,7 @@ jobs:
7777
pushd docs
7878
conda env create -f environment.yml
7979
conda activate jupyterlab_server_documentation
80+
pip install ..
8081
make html
8182
conda deactivate
8283
popd

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
include README.md
22
include LICENSE
33
include setupbase.py
4+
include jupyterlab_server/rest-api.yml
45
include jupyterlab_server/templates/*.html
56
recursive-include jupyterlab_server/tests *.json *.json.orig *.jupyterlab-workspace
67

‎docs/environment.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,5 @@ dependencies:
1111
- pip:
1212
- autodoc-traits
1313
- pydata_sphinx_theme
14+
- sphinxcontrib-openapi
15+
- numpydoc

‎docs/source/api/app.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
=========================
2-
Application configuration
3-
=========================
1+
===========
2+
Application
3+
===========
44

55
Module: :mod:`jupyterlab_server.app`
66
====================================

‎docs/source/api/config.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
=========================
2-
JupyterLab Server Config
3-
=========================
1+
======
2+
Config
3+
======
44

55
Module: :mod:`jupyterlab_server.config`
66
=======================================

‎docs/source/api/index.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,9 @@ JupyterLab Server API
55
JupyterLab Server API Reference:
66

77
.. toctree::
8+
:maxdepth: 1
9+
:caption: Contents:
10+
811
app
912
config
13+
rest

‎docs/source/api/rest.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
--------
2+
REST API
3+
--------
4+
5+
The same JupyterLab Server API spec, as found here, is available in an interactive form
6+
`here (on swagger's petstore) <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterlab/jupyterlab_server/master/jupyterlab_server/rest-api.yml#!/default>`__.
7+
The `OpenAPI Initiative`_ (fka Swagger™) is a project used to describe
8+
and document RESTful APIs.
9+
10+
.. openapi:: ../../../jupyterlab_server/rest-api.yml
11+
12+
13+
.. _OpenAPI Initiative: https://www.openapis.org/

‎docs/source/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@
4747
'autodoc_traits',
4848
'sphinx.ext.autodoc',
4949
'sphinx.ext.intersphinx',
50+
'sphinxcontrib.openapi',
51+
'sphinx.ext.napoleon',
5052
'sphinx.ext.mathjax',
5153
'sphinx_copybutton'
5254
]

‎jupyterlab_server/rest-api.yml‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterlab/jupyterlab_server/master/docs/rest-api.yml#/default
2+
openapi: "3.0.3"
3+
info:
4+
title: JupyterLab Server
5+
description: The REST API for JupyterLab Server
6+
version: 1.0.0
7+
license:
8+
name: BSD-3-Clause
9+
10+
paths:
11+
/lab/api/listings/%40jupyterlab/extensionmanager-extension/listings.json:
12+
get:
13+
summary: Get Extension Listings Specs
14+
description: |
15+
Gets the list of extension metadata for the application
16+
responses:
17+
"200":
18+
description: The Extension Listing specs
19+
content:
20+
application/json:
21+
schema:
22+
properties:
23+
blocked_extension_uris:
24+
type: array
25+
description: list of blocked extension uris
26+
items:
27+
type: string
28+
allowed_extension_uris:
29+
type: array
30+
description: list of allowed extension uris
31+
items:
32+
type: string
33+
blocked_extensions:
34+
type: array
35+
description: list of blocked extensions
36+
items:
37+
$ref: "#/components/schemas/ListEntry"
38+
allowed_extensions:
39+
type: array
40+
description: list of blocked extensions
41+
items:
42+
$ref: "#/components/schemas/ListEntry"
43+
44+
/lab/api/settings/:
45+
get:
46+
summary: Get Settings List
47+
description: |
48+
Gets the list of all application settings data
49+
responses:
50+
"200":
51+
description: The Application Settings Data
52+
content:
53+
application/json:
54+
schema:
55+
properties:
56+
settings:
57+
type: array
58+
description: List of application settings entries
59+
items:
60+
$ref: "#/components/schemas/SettingsEntry"
61+
62+
/lab/api/settings/{schema_name}:
63+
parameters:
64+
- name: schema_name
65+
description: Schema Name
66+
in: path
67+
required: true
68+
schema:
69+
type: string
70+
get:
71+
summary: Get the settings data for a given schema
72+
description: |
73+
Gets the settings data for a given schema
74+
responses:
75+
"200":
76+
description: The Settings Data
77+
content:
78+
application/json:
79+
schema:
80+
$ref: "#/components/schemas/SettingsEntry"
81+
put:
82+
summary: Override the settings data for a given schema
83+
description: |
84+
Overrides the settings data for a given schema
85+
requestBody:
86+
required: true
87+
description: raw settings data
88+
content:
89+
application/json:
90+
schema:
91+
type: object
92+
properties:
93+
raw:
94+
type: string
95+
responses:
96+
"204":
97+
description: The setting has been updated
98+
99+
/lab/api/themes/{theme_file}:
100+
parameters:
101+
- name: theme_file
102+
description: Theme file path
103+
in: path
104+
required: true
105+
schema:
106+
type: string
107+
get:
108+
summary: Get a static theme file
109+
description: |
110+
Gets the static theme file at a given path
111+
responses:
112+
"200":
113+
description: The Theme File
114+
115+
/lab/api/translations/:
116+
get:
117+
summary: Get Translation Bundles
118+
description: |
119+
Gets the list of translation bundles
120+
responses:
121+
"200":
122+
description: The Extension Listing specs
123+
content:
124+
application/json:
125+
schema:
126+
type: object
127+
properties:
128+
data:
129+
type: object
130+
additionalProperties:
131+
$ref: "#/components/schemas/TranslationEntry"
132+
message:
133+
type: string
134+
135+
/lab/api/translations/{locale}:
136+
parameters:
137+
- name: locale
138+
description: Locale name
139+
in: path
140+
required: true
141+
schema:
142+
type: string
143+
get:
144+
summary: Get the translation data for locale
145+
description: |
146+
Gets the translation data for a given locale
147+
responses:
148+
"200":
149+
description: The Local Data
150+
content:
151+
application/json:
152+
schema:
153+
type: object
154+
properties:
155+
data:
156+
type: object
157+
message:
158+
type: string
159+
160+
/lab/api/workspaces/:
161+
get:
162+
summary: Get Workspace Data
163+
description: |
164+
Gets the list of workspace data
165+
responses:
166+
"200":
167+
description: The Workspace specs
168+
content:
169+
application/json:
170+
schema:
171+
type: object
172+
properties:
173+
workspaces:
174+
type: object
175+
properties:
176+
ids:
177+
type: array
178+
items:
179+
type: string
180+
values:
181+
type: array
182+
items:
183+
$ref: "#/components/schemas/Workspace"
184+
185+
/lab/api/workspaces/{space_name}:
186+
parameters:
187+
- name: space_name
188+
description: Workspace name
189+
in: path
190+
required: true
191+
schema:
192+
type: string
193+
get:
194+
summary: Get the workspace data for name
195+
description: |
196+
Gets the workspace data for a given workspace name
197+
responses:
198+
"200":
199+
description: The Workspace Data
200+
content:
201+
application/json:
202+
schema:
203+
$ref: "#/components/schemas/Workspace"
204+
put:
205+
summary: Override the workspace data for a given name
206+
description: |
207+
Overrides the workspace data for a given workspace name
208+
requestBody:
209+
required: true
210+
description: raw workspace data
211+
content:
212+
application/json:
213+
schema:
214+
$ref: "#/components/schemas/Workspace"
215+
responses:
216+
"204":
217+
description: The workspace has been updated
218+
219+
delete:
220+
summary: Delete the workspace data for a given name
221+
description: |
222+
Deletes the workspace data for a given workspace name
223+
responses:
224+
"204":
225+
description: The workspace has been deleted
226+
227+
components:
228+
schemas:
229+
ListEntry:
230+
type: object
231+
properties:
232+
name:
233+
type: string
234+
regexp:
235+
type: string
236+
type:
237+
type: string
238+
reason:
239+
type: string
240+
creation_date:
241+
type: string
242+
last_update_date:
243+
type: string
244+
SettingsEntry:
245+
type: object
246+
properties:
247+
id:
248+
type: string
249+
schema:
250+
type: object
251+
version:
252+
type: string
253+
raw:
254+
type: string
255+
settings:
256+
type: object
257+
warning:
258+
type: string
259+
nullable: true
260+
last_modified:
261+
type: string
262+
nullable: true
263+
created:
264+
type: string
265+
nullable: true
266+
TranslationEntry:
267+
type: object
268+
properties:
269+
data:
270+
type: object
271+
properties:
272+
displayName:
273+
type: string
274+
nativeName:
275+
type: string
276+
message:
277+
type: string
278+
Workspace:
279+
type: object
280+
properties:
281+
data:
282+
type: object
283+
metadata:
284+
type: object
285+
properties:
286+
id:
287+
type: string
288+
last_modified:
289+
type: string
290+
created:
291+
type: string

‎jupyterlab_server/tests/test_listings_api.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
from .utils import validate_request
3+
4+
5+
async def test_get_listing(jp_fetch, labserverapp):
6+
url = r"lab/api/listings/@jupyterlab/extensionmanager-extension/listings.json"
7+
r = await jp_fetch(*url.split('/'))
8+
validate_request(r)

0 commit comments

Comments
 (0)