edx-api-doc-tools 3.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- edx_api_doc_tools/__init__.py +51 -0
- edx_api_doc_tools/apps.py +38 -0
- edx_api_doc_tools/conf/locale/config.yaml +85 -0
- edx_api_doc_tools/conf_utils.py +206 -0
- edx_api_doc_tools/data.py +94 -0
- edx_api_doc_tools/internal_utils.py +41 -0
- edx_api_doc_tools/urls.py +10 -0
- edx_api_doc_tools/view_utils.py +176 -0
- edx_api_doc_tools-3.1.0.dist-info/METADATA +121 -0
- edx_api_doc_tools-3.1.0.dist-info/RECORD +13 -0
- edx_api_doc_tools-3.1.0.dist-info/WHEEL +5 -0
- edx_api_doc_tools-3.1.0.dist-info/licenses/LICENSE.txt +180 -0
- edx_api_doc_tools-3.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Tools for writing and generating API documentation for Open edX REST APIs.
|
|
3
|
+
|
|
4
|
+
In this file is the public Python API for REST documentation.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
# The functions are split into separate files for code organization,
|
|
8
|
+
# but they are imported into here so they can be imported
|
|
9
|
+
# directly from `edx_api_doc_tools`.
|
|
10
|
+
|
|
11
|
+
from importlib.metadata import version
|
|
12
|
+
|
|
13
|
+
# Expose OpenAPI module through the edx_api_doc_tools package
|
|
14
|
+
# so that general users don't have to know about drf_yasg.
|
|
15
|
+
from drf_yasg import openapi
|
|
16
|
+
|
|
17
|
+
# When adding new functions to this API,
|
|
18
|
+
# add them to the appropriate sub-module,
|
|
19
|
+
# and then "expose" them by importing them here.
|
|
20
|
+
# Use explicit imports (as opposed to wildcard imports)
|
|
21
|
+
# so that we hide internal names and keep this module
|
|
22
|
+
# a nice catalog of functions.
|
|
23
|
+
from .conf_utils import (
|
|
24
|
+
ApiSchemaGenerator,
|
|
25
|
+
get_docs_cache_timeout,
|
|
26
|
+
get_docs_urls,
|
|
27
|
+
make_api_info,
|
|
28
|
+
make_docs_data_view,
|
|
29
|
+
make_docs_ui_view,
|
|
30
|
+
make_docs_urls,
|
|
31
|
+
)
|
|
32
|
+
from .data import (
|
|
33
|
+
FILE_PARAM,
|
|
34
|
+
PARAM_TYPES,
|
|
35
|
+
ParameterLocation,
|
|
36
|
+
parameter,
|
|
37
|
+
path_parameter,
|
|
38
|
+
query_parameter,
|
|
39
|
+
string_parameter,
|
|
40
|
+
)
|
|
41
|
+
from .view_utils import (
|
|
42
|
+
exclude_schema,
|
|
43
|
+
exclude_schema_for,
|
|
44
|
+
exclude_schema_for_all,
|
|
45
|
+
is_schema_request,
|
|
46
|
+
schema,
|
|
47
|
+
schema_for,
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
__version__ = version("edx-api-doc-tools")
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""
|
|
2
|
+
App for documenting REST APIs, generating spec files, and serving specs as a UI.
|
|
3
|
+
|
|
4
|
+
Under the hood, this app uses drf-yasg
|
|
5
|
+
("Yet Another Swagger Generator for DRF")
|
|
6
|
+
to generate API spec. It then uses Swagger to serve that spec.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from django.apps import AppConfig, apps
|
|
10
|
+
from django.core.exceptions import ImproperlyConfigured
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class EdxApiDocToolsConfig(AppConfig):
|
|
14
|
+
"""
|
|
15
|
+
Configuration for this app.
|
|
16
|
+
|
|
17
|
+
Note that 'drf_yasg' must be added to INSTALLED_APPS as well.
|
|
18
|
+
"""
|
|
19
|
+
name = 'edx_api_doc_tools'
|
|
20
|
+
verbose_name = 'edX REST API Documentation Tools'
|
|
21
|
+
|
|
22
|
+
def ready(self):
|
|
23
|
+
"""
|
|
24
|
+
Check whether 'drf_yasg' is in INSTALLED_APPS.
|
|
25
|
+
|
|
26
|
+
We prefer to throw an error upon initialization, because otherwise,
|
|
27
|
+
a developer won't know something is wrong until they try to render the
|
|
28
|
+
docs UI, at which point they'll just see a template load error.
|
|
29
|
+
|
|
30
|
+
Overrides `AppConfig.ready`.
|
|
31
|
+
"""
|
|
32
|
+
for app in apps.get_app_configs():
|
|
33
|
+
if app.label == 'drf_yasg':
|
|
34
|
+
return
|
|
35
|
+
raise ImproperlyConfigured(
|
|
36
|
+
"To use edx_api_doc_tools, "
|
|
37
|
+
"'drf_yasg' must also be added to 'INSTALLED_APPS'."
|
|
38
|
+
)
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Configuration for i18n workflow.
|
|
2
|
+
|
|
3
|
+
locales:
|
|
4
|
+
- en # English - Source Language
|
|
5
|
+
- am # Amharic
|
|
6
|
+
- ar # Arabic
|
|
7
|
+
- az # Azerbaijani
|
|
8
|
+
- bg_BG # Bulgarian (Bulgaria)
|
|
9
|
+
- bn_BD # Bengali (Bangladesh)
|
|
10
|
+
- bn_IN # Bengali (India)
|
|
11
|
+
- bs # Bosnian
|
|
12
|
+
- ca # Catalan
|
|
13
|
+
- ca@valencia # Catalan (Valencia)
|
|
14
|
+
- cs # Czech
|
|
15
|
+
- cy # Welsh
|
|
16
|
+
- da # Danish
|
|
17
|
+
- de_DE # German (Germany)
|
|
18
|
+
- el # Greek
|
|
19
|
+
- en # English
|
|
20
|
+
- en_GB # English (United Kingdom)
|
|
21
|
+
# Don't pull these until we figure out why pages randomly display in these locales,
|
|
22
|
+
# when the user's browser is in English and the user is not logged in.
|
|
23
|
+
# - en@lolcat # LOLCAT English
|
|
24
|
+
# - en@pirate # Pirate English
|
|
25
|
+
- es_419 # Spanish (Latin America)
|
|
26
|
+
- es_AR # Spanish (Argentina)
|
|
27
|
+
- es_EC # Spanish (Ecuador)
|
|
28
|
+
- es_ES # Spanish (Spain)
|
|
29
|
+
- es_MX # Spanish (Mexico)
|
|
30
|
+
- es_PE # Spanish (Peru)
|
|
31
|
+
- et_EE # Estonian (Estonia)
|
|
32
|
+
- eu_ES # Basque (Spain)
|
|
33
|
+
- fa # Persian
|
|
34
|
+
- fa_IR # Persian (Iran)
|
|
35
|
+
- fi_FI # Finnish (Finland)
|
|
36
|
+
- fil # Filipino
|
|
37
|
+
- fr # French
|
|
38
|
+
- gl # Galician
|
|
39
|
+
- gu # Gujarati
|
|
40
|
+
- he # Hebrew
|
|
41
|
+
- hi # Hindi
|
|
42
|
+
- hr # Croatian
|
|
43
|
+
- hu # Hungarian
|
|
44
|
+
- hy_AM # Armenian (Armenia)
|
|
45
|
+
- id # Indonesian
|
|
46
|
+
- it_IT # Italian (Italy)
|
|
47
|
+
- ja_JP # Japanese (Japan)
|
|
48
|
+
- kk_KZ # Kazakh (Kazakhstan)
|
|
49
|
+
- km_KH # Khmer (Cambodia)
|
|
50
|
+
- kn # Kannada
|
|
51
|
+
- ko_KR # Korean (Korea)
|
|
52
|
+
- lt_LT # Lithuanian (Lithuania)
|
|
53
|
+
- ml # Malayalam
|
|
54
|
+
- mn # Mongolian
|
|
55
|
+
- mr # Marathi
|
|
56
|
+
- ms # Malay
|
|
57
|
+
- nb # Norwegian Bokmål
|
|
58
|
+
- ne # Nepali
|
|
59
|
+
- nl_NL # Dutch (Netherlands)
|
|
60
|
+
- or # Oriya
|
|
61
|
+
- pl # Polish
|
|
62
|
+
- pt_BR # Portuguese (Brazil)
|
|
63
|
+
- pt_PT # Portuguese (Portugal)
|
|
64
|
+
- ro # Romanian
|
|
65
|
+
- ru # Russian
|
|
66
|
+
- si # Sinhala
|
|
67
|
+
- sk # Slovak
|
|
68
|
+
- sl # Slovenian
|
|
69
|
+
- sq # Albanian
|
|
70
|
+
- sr # Serbian
|
|
71
|
+
- ta # Tamil
|
|
72
|
+
- te # Telugu
|
|
73
|
+
- th # Thai
|
|
74
|
+
- tr_TR # Turkish (Turkey)
|
|
75
|
+
- uk # Ukranian
|
|
76
|
+
- ur # Urdu
|
|
77
|
+
- uz # Uzbek
|
|
78
|
+
- vi # Vietnamese
|
|
79
|
+
- zh_CN # Chinese (China)
|
|
80
|
+
- zh_HK # Chinese (Hong Kong)
|
|
81
|
+
- zh_TW # Chinese (Taiwan)
|
|
82
|
+
|
|
83
|
+
# The locales used for fake-accented English, for testing.
|
|
84
|
+
dummy_locales:
|
|
85
|
+
- eo
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Functions for setting up API doc generation & viewing in a repository.
|
|
3
|
+
|
|
4
|
+
External users: import these from __init__.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from django.conf import settings
|
|
8
|
+
from django.urls import path, re_path
|
|
9
|
+
from django.views.generic.base import RedirectView
|
|
10
|
+
from drf_yasg import openapi
|
|
11
|
+
from drf_yasg.generators import OpenAPISchemaGenerator
|
|
12
|
+
from drf_yasg.views import get_schema_view
|
|
13
|
+
from rest_framework import permissions
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def make_docs_urls(api_info, api_url_patterns=None):
|
|
17
|
+
"""
|
|
18
|
+
Create API doc views given an API info object.
|
|
19
|
+
|
|
20
|
+
Arguments:
|
|
21
|
+
api_info (openapi.Info): Information about the API.
|
|
22
|
+
api_url_patterns (list of url patterns): URL patterns that API docs will be generated for
|
|
23
|
+
|
|
24
|
+
Returns: list[RegexURLPattern]
|
|
25
|
+
A list of url patterns to the API docs.
|
|
26
|
+
|
|
27
|
+
Example::
|
|
28
|
+
|
|
29
|
+
# File: urls.py
|
|
30
|
+
from edx_api_doc_tools import make_docs_urls, make_api_info
|
|
31
|
+
urlpatterns = [ ... ] # Your URL patterns.
|
|
32
|
+
api_info = make_api_info(title="Awesome API", version="v42")
|
|
33
|
+
urlpatterns += make_docs_urls(api_info)
|
|
34
|
+
"""
|
|
35
|
+
return get_docs_urls(
|
|
36
|
+
docs_data_view=make_docs_data_view(api_info, api_url_patterns),
|
|
37
|
+
docs_ui_view=make_docs_ui_view(api_info, api_url_patterns),
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def make_api_info(
|
|
42
|
+
title="Open edX APIs",
|
|
43
|
+
version="v1",
|
|
44
|
+
email="oscm@openedx.org",
|
|
45
|
+
description="APIs for access to Open edX information",
|
|
46
|
+
):
|
|
47
|
+
"""
|
|
48
|
+
Build an API info object.
|
|
49
|
+
|
|
50
|
+
Arguments:
|
|
51
|
+
title (str): The title of the API.
|
|
52
|
+
version (str): The version of the API.
|
|
53
|
+
email (str): Contact email address for API support or questions.
|
|
54
|
+
description (str): Description of the API.
|
|
55
|
+
|
|
56
|
+
Returns: openapi.Info
|
|
57
|
+
"""
|
|
58
|
+
return openapi.Info(
|
|
59
|
+
title=title,
|
|
60
|
+
default_version=version,
|
|
61
|
+
contact=openapi.Contact(email=email),
|
|
62
|
+
description=description,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def get_docs_urls(docs_data_view, docs_ui_view):
|
|
67
|
+
"""
|
|
68
|
+
Get some reasonable URL patterns to browsable API docs and API docs data.
|
|
69
|
+
|
|
70
|
+
If these URL patterns don't work for your service,
|
|
71
|
+
feel free to construct your own.
|
|
72
|
+
|
|
73
|
+
Arguments:
|
|
74
|
+
docs_data_view (openapi.Info): JSON/YAML view for API docs data.
|
|
75
|
+
docs_ui_view (openapi.Info): Nice HTML view for API docs.
|
|
76
|
+
|
|
77
|
+
Returns: list[RegexURLPattern]
|
|
78
|
+
A list of url patterns to the API docs.
|
|
79
|
+
|
|
80
|
+
Example::
|
|
81
|
+
|
|
82
|
+
# File: urls.py
|
|
83
|
+
from edx_api_doc_tools import get_docs_urls
|
|
84
|
+
from .views import custom_doc_data_view, custom_doc_ui_view
|
|
85
|
+
urlpatterns = [ ... ] # Your URL patterns.
|
|
86
|
+
urlpatterns += get_docs_urls(custom_doc_data_view, custom_doc_ui_view)
|
|
87
|
+
"""
|
|
88
|
+
return [
|
|
89
|
+
re_path(
|
|
90
|
+
r'^swagger(?P<format>\.json|\.yaml)$',
|
|
91
|
+
docs_data_view,
|
|
92
|
+
name='apidocs-data',
|
|
93
|
+
),
|
|
94
|
+
path('api-docs/', docs_ui_view,
|
|
95
|
+
name='apidocs-ui',
|
|
96
|
+
),
|
|
97
|
+
path('swagger/', RedirectView.as_view(pattern_name='apidocs-ui', permanent=False),
|
|
98
|
+
name='apidocs-ui-swagger',
|
|
99
|
+
),
|
|
100
|
+
]
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def make_docs_data_view(api_info, api_url_patterns=None):
|
|
104
|
+
"""
|
|
105
|
+
Build View for API documentation data (either JSON or YAML).
|
|
106
|
+
|
|
107
|
+
Arguments:
|
|
108
|
+
api_info (openapi.Info): Information about the API.
|
|
109
|
+
api_url_patterns (list of url patterns): URL patterns that API docs will be generated for
|
|
110
|
+
|
|
111
|
+
Returns: View
|
|
112
|
+
|
|
113
|
+
Example::
|
|
114
|
+
|
|
115
|
+
from edx_api_doc_tools import make_api_info, make_docs_data_view
|
|
116
|
+
api_info = make_api_info(title="Awesome API", version="v42")
|
|
117
|
+
my_data_view = make_docs_data_view(api_info)
|
|
118
|
+
"""
|
|
119
|
+
schema_generator = get_schema_generator(api_url_patterns)
|
|
120
|
+
|
|
121
|
+
return get_schema_view(
|
|
122
|
+
api_info,
|
|
123
|
+
generator_class=schema_generator,
|
|
124
|
+
public=True,
|
|
125
|
+
permission_classes=(permissions.AllowAny,),
|
|
126
|
+
patterns=api_url_patterns,
|
|
127
|
+
).without_ui(cache_timeout=get_docs_cache_timeout())
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def make_docs_ui_view(api_info, api_url_patterns=None):
|
|
131
|
+
"""
|
|
132
|
+
Build View for browsable API documentation.
|
|
133
|
+
|
|
134
|
+
Arguments:
|
|
135
|
+
api_info (openapi.Info): Information about the API.
|
|
136
|
+
api_url_patterns (list of url patterns): URL patterns that API docs will be generated for
|
|
137
|
+
|
|
138
|
+
Returns: View
|
|
139
|
+
|
|
140
|
+
Example::
|
|
141
|
+
|
|
142
|
+
from edx_api_doc_tools import make_api_info, make_docs_ui_view
|
|
143
|
+
api_info = make_api_info(title="Awesome API", version="v42")
|
|
144
|
+
my_ui_view = make_docs_ui_view(api_info)
|
|
145
|
+
"""
|
|
146
|
+
schema_generator = get_schema_generator(api_url_patterns)
|
|
147
|
+
|
|
148
|
+
return get_schema_view(
|
|
149
|
+
api_info,
|
|
150
|
+
generator_class=schema_generator,
|
|
151
|
+
public=True,
|
|
152
|
+
permission_classes=(permissions.AllowAny,),
|
|
153
|
+
patterns=api_url_patterns,
|
|
154
|
+
).with_ui('swagger', cache_timeout=get_docs_cache_timeout())
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class ApiSchemaGenerator(OpenAPISchemaGenerator):
|
|
158
|
+
"""
|
|
159
|
+
A schema generator for ``/api/*``.
|
|
160
|
+
|
|
161
|
+
Only includes endpoints in the ``/api/*`` url tree, and sets the path prefix
|
|
162
|
+
appropriately.
|
|
163
|
+
"""
|
|
164
|
+
|
|
165
|
+
def get_endpoints(self, request):
|
|
166
|
+
"""
|
|
167
|
+
Return dict of endpoints to be displayed.
|
|
168
|
+
"""
|
|
169
|
+
endpoints = super().get_endpoints(request)
|
|
170
|
+
subpoints = {p: v for p, v in endpoints.items() if p.startswith("/api/")}
|
|
171
|
+
return subpoints
|
|
172
|
+
|
|
173
|
+
def determine_path_prefix(self, paths):
|
|
174
|
+
"""
|
|
175
|
+
Return common prefix for all paths.
|
|
176
|
+
"""
|
|
177
|
+
return "/api/"
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def get_schema_generator(patterns):
|
|
181
|
+
"""
|
|
182
|
+
Get correct schema generator.
|
|
183
|
+
|
|
184
|
+
Defaults to ApiSchemaGenerator if no url patterns are specified, meaning
|
|
185
|
+
that base path will be "/api".
|
|
186
|
+
|
|
187
|
+
Arguments:
|
|
188
|
+
patterns (list of url patterns): URL patterns that API docs will be generated for
|
|
189
|
+
|
|
190
|
+
Returns:
|
|
191
|
+
Schema generator object.
|
|
192
|
+
"""
|
|
193
|
+
if patterns:
|
|
194
|
+
return OpenAPISchemaGenerator
|
|
195
|
+
else:
|
|
196
|
+
return ApiSchemaGenerator
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def get_docs_cache_timeout():
|
|
200
|
+
"""
|
|
201
|
+
Return OPENAPI_CACHE_TIMEOUT setting, or zero if it's not defined.
|
|
202
|
+
"""
|
|
203
|
+
try:
|
|
204
|
+
return settings.OPENAPI_CACHE_TIMEOUT
|
|
205
|
+
except AttributeError:
|
|
206
|
+
return 0
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Data definitions for API schemas.
|
|
3
|
+
|
|
4
|
+
Mostly, we just use the definitions in drf_yasg.openapi
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from drf_yasg import openapi
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Python 3 doesn't have a builtin `file` type,
|
|
11
|
+
# so we need a constant instead.
|
|
12
|
+
FILE_PARAM = 'file'
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
# A map from builtin Python types to the corresponding OpenAPI type string constant.
|
|
16
|
+
# The built-in types can be passed to the `parameter` function in place of the
|
|
17
|
+
# OpenAPI strings for convenience.
|
|
18
|
+
_PARAM_TYPE_MAP = {
|
|
19
|
+
object: openapi.TYPE_OBJECT,
|
|
20
|
+
str: openapi.TYPE_STRING,
|
|
21
|
+
float: openapi.TYPE_NUMBER,
|
|
22
|
+
int: openapi.TYPE_INTEGER,
|
|
23
|
+
bool: openapi.TYPE_BOOLEAN,
|
|
24
|
+
list: openapi.TYPE_ARRAY,
|
|
25
|
+
FILE_PARAM: openapi.TYPE_FILE,
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
PARAM_TYPES = frozenset(_PARAM_TYPE_MAP.keys())
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def path_parameter(name, param_type, description=None):
|
|
33
|
+
"""
|
|
34
|
+
Define a parameter in the endpoint's path.
|
|
35
|
+
|
|
36
|
+
Type must still be specified.
|
|
37
|
+
"""
|
|
38
|
+
return parameter(name, ParameterLocation.PATH, param_type, description=description)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def query_parameter(name, param_type, description=None):
|
|
42
|
+
"""
|
|
43
|
+
Define a parameter in the endpoint's querystring.
|
|
44
|
+
|
|
45
|
+
Type must still be specified.
|
|
46
|
+
"""
|
|
47
|
+
return parameter(name, ParameterLocation.QUERY, param_type, description=description)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def string_parameter(name, in_, description=None):
|
|
51
|
+
"""
|
|
52
|
+
Define a string parameter.
|
|
53
|
+
|
|
54
|
+
Location must still be specified.
|
|
55
|
+
"""
|
|
56
|
+
return parameter(name, in_, str, description=description)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def parameter(name, in_, param_type, description=None):
|
|
60
|
+
"""
|
|
61
|
+
Define a typed parameter.
|
|
62
|
+
|
|
63
|
+
Arguments:
|
|
64
|
+
name (str): The name of the parameter.
|
|
65
|
+
in_ (ParameterLocation attribute): How the parameter is passed in.
|
|
66
|
+
param_type (type|str): a member of `PARAM_TYPES`.
|
|
67
|
+
description (str): Description of the parameter.
|
|
68
|
+
|
|
69
|
+
Returns: openapi.Parameter
|
|
70
|
+
"""
|
|
71
|
+
try:
|
|
72
|
+
openapi_type = _PARAM_TYPE_MAP[param_type]
|
|
73
|
+
except KeyError as error:
|
|
74
|
+
raise ValueError(
|
|
75
|
+
f'param_type must be a member of the set {PARAM_TYPES}'
|
|
76
|
+
) from error
|
|
77
|
+
return openapi.Parameter(
|
|
78
|
+
name,
|
|
79
|
+
in_,
|
|
80
|
+
type=openapi_type,
|
|
81
|
+
description=description,
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class ParameterLocation:
|
|
86
|
+
"""
|
|
87
|
+
Location of API parameter in request.
|
|
88
|
+
"""
|
|
89
|
+
BODY = openapi.IN_BODY
|
|
90
|
+
PATH = openapi.IN_PATH
|
|
91
|
+
QUERY = openapi.IN_QUERY
|
|
92
|
+
FORM = openapi.IN_FORM
|
|
93
|
+
HEADER = openapi.IN_HEADER
|
|
94
|
+
__ALL__ = {BODY, PATH, QUERY, FORM, HEADER}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Utility functions internal to this package.
|
|
3
|
+
"""
|
|
4
|
+
import textwrap
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def dedent(text):
|
|
8
|
+
"""
|
|
9
|
+
Dedent multi-line text nicely.
|
|
10
|
+
|
|
11
|
+
An initial empty line is ignored so that triple-quoted strings don't need
|
|
12
|
+
to start with a backslash.
|
|
13
|
+
"""
|
|
14
|
+
if "\n" in text:
|
|
15
|
+
first, rest = text.split("\n", 1)
|
|
16
|
+
if not first.strip():
|
|
17
|
+
# First line is blank, discard it.
|
|
18
|
+
text = rest
|
|
19
|
+
return textwrap.dedent(text)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def split_docstring(docstring):
|
|
23
|
+
"""
|
|
24
|
+
Split a docstring into a summary and a description.
|
|
25
|
+
|
|
26
|
+
Arguments:
|
|
27
|
+
docstring (str): the docstring
|
|
28
|
+
|
|
29
|
+
Returns:
|
|
30
|
+
summary (str or None): a one-line summary.
|
|
31
|
+
description (str or None): the multi-line description.
|
|
32
|
+
"""
|
|
33
|
+
summary = None
|
|
34
|
+
description = None
|
|
35
|
+
if docstring:
|
|
36
|
+
doc_lines = docstring.strip().split("\n")
|
|
37
|
+
if doc_lines:
|
|
38
|
+
summary = doc_lines[0].strip()
|
|
39
|
+
if len(doc_lines) > 1:
|
|
40
|
+
description = dedent("\n".join(doc_lines[1:]))
|
|
41
|
+
return summary, description
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Utilities for annotating API views with schema info.
|
|
3
|
+
|
|
4
|
+
External users: import these from __init__.
|
|
5
|
+
"""
|
|
6
|
+
from django.utils.decorators import method_decorator
|
|
7
|
+
from drf_yasg.utils import swagger_auto_schema
|
|
8
|
+
from rest_framework.viewsets import ViewSet
|
|
9
|
+
|
|
10
|
+
from .internal_utils import dedent, split_docstring
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def schema_for(method_name, docstring=None, **schema_kwargs):
|
|
14
|
+
"""
|
|
15
|
+
Decorate a class to specify a schema for one of its methods.
|
|
16
|
+
|
|
17
|
+
Useful when the method you are describing is not defined inside of your
|
|
18
|
+
class body, but is instead defined somewhere up in the DRF view hierarchy.
|
|
19
|
+
(For applying a schema directly to a method, use the :func:`.schema`
|
|
20
|
+
decorator).
|
|
21
|
+
|
|
22
|
+
DRF method names include: ``list``, ``retrieve``, ``get``, ``post``,
|
|
23
|
+
``create``, ``put``, ``update``, ``patch``, ``partial_update``,
|
|
24
|
+
``delete``, and ``destroy``.
|
|
25
|
+
|
|
26
|
+
Arguments:
|
|
27
|
+
method_name (str): Name of the method to decorate.
|
|
28
|
+
docstring (str): Optional summary and description of the operation,
|
|
29
|
+
which takes the same format that :func:`.schema` expects of function
|
|
30
|
+
docstrings (that is, a summary line, followed by a newline,
|
|
31
|
+
followed by one or more lines of description).
|
|
32
|
+
**schema_kwargs: kwargs to pass to :func:`.schema`.
|
|
33
|
+
"""
|
|
34
|
+
def schema_for_inner(view_class):
|
|
35
|
+
"""
|
|
36
|
+
Decorate a view class with the specified schema.
|
|
37
|
+
"""
|
|
38
|
+
summary, description = split_docstring(docstring)
|
|
39
|
+
decorated_class = method_decorator(
|
|
40
|
+
name=method_name,
|
|
41
|
+
decorator=schema(
|
|
42
|
+
summary=summary, description=description, **schema_kwargs
|
|
43
|
+
),
|
|
44
|
+
)(view_class)
|
|
45
|
+
return decorated_class
|
|
46
|
+
return schema_for_inner
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def exclude_schema_for(*method_names):
|
|
50
|
+
"""
|
|
51
|
+
Decorate a class to exlcude one or more of of its methods from the API docs.
|
|
52
|
+
|
|
53
|
+
Arguments:
|
|
54
|
+
method_names (list[str]): Names of view methods whose operations will be
|
|
55
|
+
excluded from the generated API documentation.
|
|
56
|
+
|
|
57
|
+
Example::
|
|
58
|
+
|
|
59
|
+
@schema_for('get', ...)
|
|
60
|
+
@schema_for('delete', ...)
|
|
61
|
+
@exclude_schema_for('put', 'patch')
|
|
62
|
+
class MyView(RetrieveUpdateDestroyAPIView):
|
|
63
|
+
pass
|
|
64
|
+
"""
|
|
65
|
+
def exclude_schema_for_inner(view_class):
|
|
66
|
+
"""
|
|
67
|
+
Decorate a view class to exclude specified methods.
|
|
68
|
+
"""
|
|
69
|
+
for method_name in method_names:
|
|
70
|
+
method_decorator(
|
|
71
|
+
name=method_name, decorator=exclude_schema
|
|
72
|
+
)(view_class)
|
|
73
|
+
return view_class
|
|
74
|
+
return exclude_schema_for_inner
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def exclude_schema_for_all(view_class):
|
|
78
|
+
"""
|
|
79
|
+
Decorate a class to exlcude all of its methods from the API docs.
|
|
80
|
+
|
|
81
|
+
Arguments:
|
|
82
|
+
view_class (type): A type, typically a subclass of View or ViewSet.
|
|
83
|
+
|
|
84
|
+
Example::
|
|
85
|
+
|
|
86
|
+
@exclude_schema_for_all
|
|
87
|
+
class MyView(RetrieveUpdateDestroyAPIView):
|
|
88
|
+
pass
|
|
89
|
+
"""
|
|
90
|
+
all_viewset_api_methods = {
|
|
91
|
+
'list', 'retrieve', 'create', 'update', 'partial_update', 'destroy'
|
|
92
|
+
}
|
|
93
|
+
all_view_api_methods = {
|
|
94
|
+
'get', 'post', 'put', 'patch', 'delete'
|
|
95
|
+
}
|
|
96
|
+
is_viewset = issubclass(view_class, ViewSet)
|
|
97
|
+
all_api_methods = all_viewset_api_methods if is_viewset else all_view_api_methods
|
|
98
|
+
methods_to_exclude = {
|
|
99
|
+
method for method in all_api_methods if hasattr(view_class, method)
|
|
100
|
+
}
|
|
101
|
+
return exclude_schema_for(*methods_to_exclude)(view_class)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def schema(
|
|
105
|
+
body=None,
|
|
106
|
+
parameters=None,
|
|
107
|
+
responses=None,
|
|
108
|
+
summary=None,
|
|
109
|
+
description=None,
|
|
110
|
+
):
|
|
111
|
+
"""
|
|
112
|
+
Decorate an API-endpoint-handling function to specify its schema.
|
|
113
|
+
|
|
114
|
+
The operation summary and description are taken from the function docstring. All
|
|
115
|
+
description fields should be in Markdown and will be automatically dedented.
|
|
116
|
+
|
|
117
|
+
Arguments:
|
|
118
|
+
body: Optional payload used for POST, PUT, and PATCH requests.
|
|
119
|
+
Accepts a serializer class.
|
|
120
|
+
parameters (list[openapi.Parameter]): Optional list of parameters to
|
|
121
|
+
the API endpoint.
|
|
122
|
+
responses (dict[int, object]): Optional map from HTTP statuses to either:
|
|
123
|
+
* a serializer class corresponding to that status
|
|
124
|
+
* a string describing when that status occurs
|
|
125
|
+
* an openapi.Schema object
|
|
126
|
+
* `None`, which indicates "don't include this response".
|
|
127
|
+
summary (str): One-line summary of operation.
|
|
128
|
+
If None, we attempt to extract it from the first line of the docstring.
|
|
129
|
+
description (str): Optional multi-line description of operation.
|
|
130
|
+
If None, we attempt to extract it from the rest of the docstring.
|
|
131
|
+
request_body (Serializer): Optional serializer class corresponding to the body of the request.
|
|
132
|
+
"""
|
|
133
|
+
for param in parameters or ():
|
|
134
|
+
param.description = dedent(param.description)
|
|
135
|
+
|
|
136
|
+
def schema_inner(view_func):
|
|
137
|
+
"""
|
|
138
|
+
Decorate a view function with the specified schema.
|
|
139
|
+
"""
|
|
140
|
+
docstring_summary, docstring_description = split_docstring(view_func.__doc__)
|
|
141
|
+
final_summary = summary or docstring_summary
|
|
142
|
+
final_description = description or docstring_description or final_summary
|
|
143
|
+
return swagger_auto_schema(
|
|
144
|
+
request_body=body,
|
|
145
|
+
manual_parameters=parameters,
|
|
146
|
+
responses=responses,
|
|
147
|
+
operation_summary=final_summary,
|
|
148
|
+
operation_description=final_description,
|
|
149
|
+
)(view_func)
|
|
150
|
+
return schema_inner
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def exclude_schema(view_func):
|
|
154
|
+
"""
|
|
155
|
+
Decorate an API-endpoint-handling function to exclude it from the API docs.
|
|
156
|
+
|
|
157
|
+
Example::
|
|
158
|
+
|
|
159
|
+
class MyView(APIView):
|
|
160
|
+
|
|
161
|
+
@schema(...)
|
|
162
|
+
def get(...):
|
|
163
|
+
pass
|
|
164
|
+
|
|
165
|
+
@exclude_schema
|
|
166
|
+
def post(...):
|
|
167
|
+
pass
|
|
168
|
+
"""
|
|
169
|
+
return swagger_auto_schema(auto_schema=None)(view_func)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def is_schema_request(request):
|
|
173
|
+
"""
|
|
174
|
+
Return whether this request is serving an OpenAPI schema.
|
|
175
|
+
"""
|
|
176
|
+
return request.query_params.get('format') == 'openapi'
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: edx-api-doc-tools
|
|
3
|
+
Version: 3.1.0
|
|
4
|
+
Summary: Tools for writing and generating API documentation for edX REST APIs
|
|
5
|
+
Author-email: Open edX Project <oscm@openedx.org>
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/openedx/api-doc-tools
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Framework :: Django
|
|
10
|
+
Classifier: Framework :: Django :: 4.2
|
|
11
|
+
Classifier: Framework :: Django :: 5.2
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Natural Language :: English
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Description-Content-Type: text/x-rst
|
|
18
|
+
License-File: LICENSE.txt
|
|
19
|
+
Requires-Dist: Django
|
|
20
|
+
Requires-Dist: djangorestframework>=3.2.0
|
|
21
|
+
Requires-Dist: drf-yasg
|
|
22
|
+
Requires-Dist: setuptools
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
edX API Documentation Tools
|
|
26
|
+
===========================
|
|
27
|
+
|
|
28
|
+
|pypi| |CI| |codecov| |readthedocs| |pyversions| |license|
|
|
29
|
+
|
|
30
|
+
A toolkit for documenting REST APIs that are created with `DRF`_.
|
|
31
|
+
|
|
32
|
+
.. _DRF: https://www.django-rest-framework.org/
|
|
33
|
+
|
|
34
|
+
The tools use `drf-yasg`_ (DRF, yet another Swagger generator) to generate an
|
|
35
|
+
`OpenAPI Specification`_, which is a .json/.yaml file that describes your API.
|
|
36
|
+
Additionally, this package makes it easy to configure your service to expose
|
|
37
|
+
generated OpenAPI specification under `/api-docs.yaml` and to serve interactive
|
|
38
|
+
documentation under `/api-docs`.
|
|
39
|
+
|
|
40
|
+
.. _drf-yasg: https://github.com/axnsan12/drf-yasg
|
|
41
|
+
.. _OpenAPI Specification: https://swagger.io/docs/specification/about/
|
|
42
|
+
|
|
43
|
+
This library was developed for use with `Open edX`_ services, but could be used
|
|
44
|
+
to document any Django REST Framework API.
|
|
45
|
+
|
|
46
|
+
.. _Open edX: https://open.edx.org/
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
Quick Start
|
|
50
|
+
-----------
|
|
51
|
+
|
|
52
|
+
To start using this tool in your project, see
|
|
53
|
+
`Adding edx-api-doc-tools to your project <docs/adding.rst>`_.
|
|
54
|
+
|
|
55
|
+
To write docs using this tool, see
|
|
56
|
+
`Writing API documentation <docs/writing.rst>`_.
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
Documentation
|
|
60
|
+
-------------
|
|
61
|
+
|
|
62
|
+
Comphrehensive documentation is coming soon. For now, check out the `example/`
|
|
63
|
+
directory, which shows a fake API using these tools to generate documentation.
|
|
64
|
+
|
|
65
|
+
License
|
|
66
|
+
-------
|
|
67
|
+
|
|
68
|
+
The code in this repository is licensed under the Apache Software License 2.0
|
|
69
|
+
unless otherwise noted.
|
|
70
|
+
|
|
71
|
+
Please see `LICENSE.txt <LICENSE.txt>`_ for details.
|
|
72
|
+
|
|
73
|
+
How To Contribute
|
|
74
|
+
-----------------
|
|
75
|
+
|
|
76
|
+
Contributions are very welcome. Please read `How To Contribute`__ for details.
|
|
77
|
+
Even though they were written with `edx-platform` in mind, the guidelines
|
|
78
|
+
should be followed for all Open edX projects.
|
|
79
|
+
|
|
80
|
+
__ https://github.com/openedx/.github/blob/master/CONTRIBUTING.md
|
|
81
|
+
|
|
82
|
+
The pull request description template should be automatically applied if you
|
|
83
|
+
are creating a pull request from GitHub. Otherwise you can find it at
|
|
84
|
+
`PULL_REQUEST_TEMPLATE.md`_.
|
|
85
|
+
|
|
86
|
+
The issue report template should be automatically applied if you are creating
|
|
87
|
+
an issue on GitHub as well. Otherwise you can find it at `ISSUE_TEMPLATE.md`_.
|
|
88
|
+
|
|
89
|
+
.. _PULL_REQUEST_TEMPLATE.md: .github/PULL_REQUEST_TEMPLATE.md
|
|
90
|
+
.. _ISSUE_TEMPLATE.md: .github/ISSUE_TEMPLATE.md
|
|
91
|
+
|
|
92
|
+
Reporting Security Issues
|
|
93
|
+
-------------------------
|
|
94
|
+
|
|
95
|
+
Please do not report security issues in public. Please email security@openedx.org.
|
|
96
|
+
|
|
97
|
+
Getting Help
|
|
98
|
+
------------
|
|
99
|
+
|
|
100
|
+
Have a question about this repository, or about the Open edX project in general? Please refer to this `list of resources <https://open.edx.org/getting-help>`_ if you need any assistance.
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
.. |pypi| image:: https://img.shields.io/pypi/v/edx-api-doc-tools.svg
|
|
105
|
+
:target: https://pypi.python.org/pypi/edx-api-doc-tools/
|
|
106
|
+
:alt: PyPI
|
|
107
|
+
.. |CI| image:: https://github.com/openedx/api-doc-tools/actions/workflows/release.yml/badge.svg?branch=master
|
|
108
|
+
:target: https://github.com/openedx/api-doc-tools/actions/workflows/release.yml
|
|
109
|
+
:alt: CI
|
|
110
|
+
.. |codecov| image:: http://codecov.io/github/edx/api-doc-tools/coverage.svg?branch=master
|
|
111
|
+
:target: http://codecov.io/github/edx/api-doc-tools?branch=master
|
|
112
|
+
:alt: Codecov
|
|
113
|
+
.. |readthedocs| image:: https://readthedocs.org/projects/edx-api-doc-tools/badge/?version=latest
|
|
114
|
+
:target: http://edx-api-doc-tools.readthedocs.io/en/latest/
|
|
115
|
+
:alt: Documentation
|
|
116
|
+
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/edx-api-doc-tools.svg
|
|
117
|
+
:target: https://pypi.python.org/pypi/edx-api-doc-tools/
|
|
118
|
+
:alt: Supported
|
|
119
|
+
.. |license| image:: https://img.shields.io/github/license/edx/api-doc-tools.svg
|
|
120
|
+
:target: https://github.com/openedx/api-doc-tools/blob/master/LICENSE.txt
|
|
121
|
+
:alt: License
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
edx_api_doc_tools/__init__.py,sha256=Lhbt3OeoScf4AcX3lLcWGc0JnHz-AzHEoLlVLbWHDq8,1314
|
|
2
|
+
edx_api_doc_tools/apps.py,sha256=BR2xS0U-5J6ee1n8N39hTjhWCBznmQdmFUaoqNQjilE,1197
|
|
3
|
+
edx_api_doc_tools/conf_utils.py,sha256=z-zESlyx0a8V_i1nhqB9yo-KpJabaf3RqMnGbvpgdPk,6034
|
|
4
|
+
edx_api_doc_tools/data.py,sha256=ZiSZykMBIIV7ecURc0ByTxGcJQprENp5G68nW2NTZII,2417
|
|
5
|
+
edx_api_doc_tools/internal_utils.py,sha256=M-027PXQ99JnSGUl1Wyz45V1120Jqc428M8orlcctS8,1032
|
|
6
|
+
edx_api_doc_tools/urls.py,sha256=4Kn0d0D9NPwlnwPRruK65xV4-l11n7YL0vHLX_JcSHA,212
|
|
7
|
+
edx_api_doc_tools/view_utils.py,sha256=kdez6ANNC8BiK-S74ffTTPRwG7646xvOuz9NsIy6Q9c,5993
|
|
8
|
+
edx_api_doc_tools/conf/locale/config.yaml,sha256=jPen2DmckNDKK30axCKEd2Q2ha9oOG3IBxrJ63Pvznk,2280
|
|
9
|
+
edx_api_doc_tools-3.1.0.dist-info/licenses/LICENSE.txt,sha256=_kYizHmx1l2Y2boQzMunfQZ7A1T8r_mzfiD83ObbafY,10177
|
|
10
|
+
edx_api_doc_tools-3.1.0.dist-info/METADATA,sha256=vy12mG487ZoptwIEy_N0Hy4lvfWAHjd1RMfKeS40mRU,4466
|
|
11
|
+
edx_api_doc_tools-3.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
12
|
+
edx_api_doc_tools-3.1.0.dist-info/top_level.txt,sha256=dlsOkmkinpah1ry1rJg0M9eBUkiLXjsc99nL1YL_0qk,18
|
|
13
|
+
edx_api_doc_tools-3.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
Apache License
|
|
4
|
+
Version 2.0, January 2004
|
|
5
|
+
http://www.apache.org/licenses/
|
|
6
|
+
|
|
7
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
8
|
+
|
|
9
|
+
1. Definitions.
|
|
10
|
+
|
|
11
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
12
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
13
|
+
|
|
14
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
15
|
+
the copyright owner that is granting the License.
|
|
16
|
+
|
|
17
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
18
|
+
other entities that control, are controlled by, or are under common
|
|
19
|
+
control with that entity. For the purposes of this definition,
|
|
20
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
21
|
+
direction or management of such entity, whether by contract or
|
|
22
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
23
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
24
|
+
|
|
25
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
26
|
+
exercising permissions granted by this License.
|
|
27
|
+
|
|
28
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
29
|
+
including but not limited to software source code, documentation
|
|
30
|
+
source, and configuration files.
|
|
31
|
+
|
|
32
|
+
"Object" form shall mean any form resulting from mechanical
|
|
33
|
+
transformation or translation of a Source form, including but
|
|
34
|
+
not limited to compiled object code, generated documentation,
|
|
35
|
+
and conversions to other media types.
|
|
36
|
+
|
|
37
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
38
|
+
Object form, made available under the License, as indicated by a
|
|
39
|
+
copyright notice that is included in or attached to the work
|
|
40
|
+
(an example is provided in the Appendix below).
|
|
41
|
+
|
|
42
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
43
|
+
form, that is based on (or derived from) the Work and for which the
|
|
44
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
45
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
46
|
+
of this License, Derivative Works shall not include works that remain
|
|
47
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
48
|
+
the Work and Derivative Works thereof.
|
|
49
|
+
|
|
50
|
+
"Contribution" shall mean any work of authorship, including
|
|
51
|
+
the original version of the Work and any modifications or additions
|
|
52
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
53
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
54
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
55
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
56
|
+
means any form of electronic, verbal, or written communication sent
|
|
57
|
+
to the Licensor or its representatives, including but not limited to
|
|
58
|
+
communication on electronic mailing lists, source code control systems,
|
|
59
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
60
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
61
|
+
excluding communication that is conspicuously marked or otherwise
|
|
62
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
63
|
+
|
|
64
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
65
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
66
|
+
subsequently incorporated within the Work.
|
|
67
|
+
|
|
68
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
69
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
70
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
71
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
72
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
73
|
+
Work and such Derivative Works in Source or Object form.
|
|
74
|
+
|
|
75
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
76
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
77
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
78
|
+
(except as stated in this section) patent license to make, have made,
|
|
79
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
80
|
+
where such license applies only to those patent claims licensable
|
|
81
|
+
by such Contributor that are necessarily infringed by their
|
|
82
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
83
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
84
|
+
institute patent litigation against any entity (including a
|
|
85
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
86
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
87
|
+
or contributory patent infringement, then any patent licenses
|
|
88
|
+
granted to You under this License for that Work shall terminate
|
|
89
|
+
as of the date such litigation is filed.
|
|
90
|
+
|
|
91
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
92
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
93
|
+
modifications, and in Source or Object form, provided that You
|
|
94
|
+
meet the following conditions:
|
|
95
|
+
|
|
96
|
+
(a) You must give any other recipients of the Work or
|
|
97
|
+
Derivative Works a copy of this License; and
|
|
98
|
+
|
|
99
|
+
(b) You must cause any modified files to carry prominent notices
|
|
100
|
+
stating that You changed the files; and
|
|
101
|
+
|
|
102
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
103
|
+
that You distribute, all copyright, patent, trademark, and
|
|
104
|
+
attribution notices from the Source form of the Work,
|
|
105
|
+
excluding those notices that do not pertain to any part of
|
|
106
|
+
the Derivative Works; and
|
|
107
|
+
|
|
108
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
109
|
+
distribution, then any Derivative Works that You distribute must
|
|
110
|
+
include a readable copy of the attribution notices contained
|
|
111
|
+
within such NOTICE file, excluding those notices that do not
|
|
112
|
+
pertain to any part of the Derivative Works, in at least one
|
|
113
|
+
of the following places: within a NOTICE text file distributed
|
|
114
|
+
as part of the Derivative Works; within the Source form or
|
|
115
|
+
documentation, if provided along with the Derivative Works; or,
|
|
116
|
+
within a display generated by the Derivative Works, if and
|
|
117
|
+
wherever such third-party notices normally appear. The contents
|
|
118
|
+
of the NOTICE file are for informational purposes only and
|
|
119
|
+
do not modify the License. You may add Your own attribution
|
|
120
|
+
notices within Derivative Works that You distribute, alongside
|
|
121
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
122
|
+
that such additional attribution notices cannot be construed
|
|
123
|
+
as modifying the License.
|
|
124
|
+
|
|
125
|
+
You may add Your own copyright statement to Your modifications and
|
|
126
|
+
may provide additional or different license terms and conditions
|
|
127
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
128
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
129
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
130
|
+
the conditions stated in this License.
|
|
131
|
+
|
|
132
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
133
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
134
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
135
|
+
this License, without any additional terms or conditions.
|
|
136
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
137
|
+
the terms of any separate license agreement you may have executed
|
|
138
|
+
with Licensor regarding such Contributions.
|
|
139
|
+
|
|
140
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
141
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
142
|
+
except as required for reasonable and customary use in describing the
|
|
143
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
144
|
+
|
|
145
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
146
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
147
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
148
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
149
|
+
implied, including, without limitation, any warranties or conditions
|
|
150
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
151
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
152
|
+
appropriateness of using or redistributing the Work and assume any
|
|
153
|
+
risks associated with Your exercise of permissions under this License.
|
|
154
|
+
|
|
155
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
156
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
157
|
+
unless required by applicable law (such as deliberate and grossly
|
|
158
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
159
|
+
liable to You for damages, including any direct, indirect, special,
|
|
160
|
+
incidental, or consequential damages of any character arising as a
|
|
161
|
+
result of this License or out of the use or inability to use the
|
|
162
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
163
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
164
|
+
other commercial damages or losses), even if such Contributor
|
|
165
|
+
has been advised of the possibility of such damages.
|
|
166
|
+
|
|
167
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
168
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
169
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
170
|
+
or other liability obligations and/or rights consistent with this
|
|
171
|
+
License. However, in accepting such obligations, You may act only
|
|
172
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
173
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
174
|
+
defend, and hold each Contributor harmless for any liability
|
|
175
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
176
|
+
of your accepting any such warranty or additional liability.
|
|
177
|
+
|
|
178
|
+
END OF TERMS AND CONDITIONS
|
|
179
|
+
|
|
180
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
edx_api_doc_tools
|