def test_view(self):
schema_generator = SchemaGenerator(title='Test View',
patterns=urlpatterns2)
schema = schema_generator.get_schema()
expected = coreapi.Document(url='',
title='Test View',
content={
'example-view': {
'create':
coreapi.Link(url='/example-view/',
action='post',
fields=[]),
'read':
coreapi.Link(url='/example-view/',
action='get',
fields=[])
}
})
self.assertEquals(schema, expected)
def include_docs_urls(title=None, description=None, patterns=None):
generator = SchemaGenerator(title=title, description=description, patterns=patterns)
docs_view = SchemaView.as_view(
renderer_classes=[DocumentationRenderer, CoreJSONRenderer],
schema_generator=generator,
public=True,
)
schema_js_view = SchemaView.as_view(
renderer_classes=[SchemaJSRenderer],
schema_generator=generator,
public=True,
)
urls = [
url(r'^$', docs_view, name='docs-index'),
url(r'^schema.js$', schema_js_view, name='schema-js')
]
return include(urls, namespace='api-docs')
def __init__(self,
info,
version='',
url=None,
patterns=None,
urlconf=None):
"""
:param openapi.Info info: information about the API
:param str version: API version string; if omitted, `info.default_version` will be used
:param str url: API scheme, host and port; if ``None`` is passed and ``DEFAULT_API_URL`` is not set, the url
will be inferred from the request made against the schema view, so you should generally not need to set
this parameter explicitly; if the empty string is passed, no host and scheme will be emitted
If `url` is not ``None`` or the empty string, it must be a scheme-absolute uri (i.e. starting with http://
or https://), and any path component is ignored;
See also: :ref:`documentation on base URL construction <custom-spec-base-url>`
:param patterns: if given, only these patterns will be enumerated for inclusion in the API spec
:param urlconf: if patterns is not given, use this urlconf to enumerate patterns;
if not given, the default urlconf is used
"""
self._gen = SchemaGenerator(info.title, url,
info.get('description',
''), patterns, urlconf)
self.info = info
self.version = version
self.consumes = []
self.produces = []
if url is None and swagger_settings.DEFAULT_API_URL is not None:
url = swagger_settings.DEFAULT_API_URL
if url:
parsed_url = urlparse.urlparse(url)
if parsed_url.scheme not in ('http',
'https') or not parsed_url.netloc:
raise SwaggerGenerationError(
"`url` must be an absolute HTTP(S) url")
if parsed_url.path:
logger.warning(
"path component of api base URL %s is ignored; use FORCE_SCRIPT_NAME instead"
% url)
def test_schema_for_regular_views(self):
"""
Ensure that schema generation with an API that is not at the URL
root continues to use correct structure for link keys.
"""
generator = SchemaGenerator(title='Example API',
patterns=self.patterns)
schema = generator.get_schema()
expected = coreapi.Document(
url='',
title='Example API',
content={
'example': {
'create':
coreapi.Link(url='/api/v1/example/',
action='post',
fields=[]),
'list':
coreapi.Link(url='/api/v1/example/',
action='get',
fields=[]),
'read':
coreapi.Link(url='/api/v1/example/{id}/',
action='get',
fields=[
coreapi.Field('id',
required=True,
location='path')
]),
'sub': {
'list':
coreapi.Link(url='/api/v1/example/{id}/sub/',
action='get',
fields=[
coreapi.Field('id',
required=True,
location='path')
])
}
}
})
self.assertEqual(schema, expected)
def test_schema_for_regular_views(self):
"""
Ensure that schema generation works for ViewSet classes
with permission classes raising exceptions.
"""
generator = SchemaGenerator(title='Example API',
patterns=self.patterns)
request = factory.get('/')
schema = generator.get_schema(Request(request))
expected = coreapi.Document(url='http://testserver/',
title='Example API',
content={
'example': {
'list':
coreapi.Link(url='/example/',
action='get',
fields=[]),
},
})
assert schema == expected
def test_schema_for_regular_views(self):
"""
Ensure that schema generation works for APIView classes.
"""
generator = SchemaGenerator(title='Example API', patterns=self.patterns)
schema = generator.get_schema()
expected = coreapi.Document(
url='',
title='Example API',
content={
'example': {
'create': coreapi.Link(
url='/example/',
action='post',
fields=[]
),
'list': coreapi.Link(
url='/example/',
action='get',
fields=[]
),
'read': coreapi.Link(
url='/example/{id}/',
action='get',
fields=[
coreapi.Field('id', required=True, location='path', schema=coreschema.String())
]
),
'sub': {
'list': coreapi.Link(
url='/example/{id}/sub/',
action='get',
fields=[
coreapi.Field('id', required=True, location='path', schema=coreschema.String())
]
)
}
}
}
)
assert schema == expected
def get_schema_root_view(self, api_urls=None):
"""
Return a schema root view.
"""
schema_renderers = self.schema_renderers
schema_generator = SchemaGenerator(title=self.schema_title,
url=self.schema_url,
patterns=api_urls)
class APISchemaView(views.APIView):
_ignore_model_permissions = True
exclude_from_schema = True
renderer_classes = schema_renderers
def get(self, request, *args, **kwargs):
schema = schema_generator.get_schema(request)
if schema is None:
raise exceptions.PermissionDenied()
return Response(schema)
return APISchemaView.as_view()
def test_manually_routing_generic_view(self):
patterns = [
url(r'^test', NamingCollisionView.as_view()),
url(r'^test/retrieve/', NamingCollisionView.as_view()),
url(r'^test/update/', NamingCollisionView.as_view()),
# Fails with method names:
url(r'^test/get/', NamingCollisionView.as_view()),
url(r'^test/put/', NamingCollisionView.as_view()),
url(r'^test/delete/', NamingCollisionView.as_view()),
]
generator = SchemaGenerator(title='Naming Colisions', patterns=patterns)
schema = generator.get_schema()
self._verify_cbv_links(schema['test']['delete'], '/test/delete/')
self._verify_cbv_links(schema['test']['put'], '/test/put/')
self._verify_cbv_links(schema['test']['get'], '/test/get/')
self._verify_cbv_links(schema['test']['update'], '/test/update/')
self._verify_cbv_links(schema['test']['retrieve'], '/test/retrieve/')
self._verify_cbv_links(schema['test'], '/test', suffixes=(None, '0', None, '0'))
def get(self, request):
generator = SchemaGenerator(title='CyBorgBackup API',
patterns=None,
urlconf=None)
schema = generator.get_schema(request=request)
# python core-api doesn't support the deprecation yet, so track it
# ourselves and return it in a response header
_deprecated = []
# By default, DRF OpenAPI serialization places all endpoints in
# a single node based on their root path (/api). Instead, we want to
# group them by topic/tag so that they're categorized in the rendered
# output
document = schema._data.pop('api')
for path, node in document.items():
if isinstance(node, Object):
for action in node.values():
topic = getattr(action, 'topic', None)
if topic:
schema._data.setdefault(topic, Object())
schema._data[topic]._data[path] = node
# if isinstance(action, Object):
# for link in action.links.values():
# if link.deprecated:
# _deprecated.append(link.url)
elif isinstance(node, Link):
topic = getattr(node, 'topic', None)
if topic:
schema._data.setdefault(topic, Object())
schema._data[topic]._data[path] = node
if not schema:
raise exceptions.ValidationError(
'The schema generator did not return a schema Document')
return Response(
schema, headers={'X-Deprecated-Paths': json.dumps(_deprecated)})
def test_viewset_action_with_schema(self):
class CustomViewSet(GenericViewSet):
@action(detail=True, schema=AutoSchema(manual_fields=[
coreapi.Field(
"my_extra_field",
required=True,
location="path",
schema=coreschema.String()
),
]))
def extra_action(self, pk, **kwargs):
pass
router = SimpleRouter()
router.register(r'detail', CustomViewSet, basename='detail')
generator = SchemaGenerator()
view = generator.create_view(router.urls[0].callback, 'GET')
link = view.schema.get_link('/a/url/{id}/', 'GET', '')
fields = link.fields
assert len(fields) == 2
assert "my_extra_field" in [f.name for f in fields]
def test_manually_routing_nested_routes(self):
patterns = [
url(r'^test', simple_fbv),
url(r'^test/list/', simple_fbv),
]
generator = SchemaGenerator(title='Naming Colisions', patterns=patterns)
schema = generator.get_schema()
expected = coreapi.Document(
url='',
title='Naming Colisions',
content={
'test': {
'list': {
'list': coreapi.Link(url='/test/list/', action='get')
},
'list_0': coreapi.Link(url='/test', action='get')
}
}
)
assert expected == schema
def get_api_root_view(self, api_urls=None):
# Copy the following block from Default Router
api_root_dict = OrderedDict()
list_name = self.routes[0].name
for prefix, viewset, basename in self.registry:
api_root_dict[prefix] = list_name.format(basename=basename)
view_renderers = list(self.root_renderers)
schema_media_types = []
if api_urls and self.schema_title:
view_renderers += list(self.schema_renderers)
schema_generator = SchemaGenerator(title=self.schema_title,
url=self.schema_url,
patterns=api_urls)
schema_media_types = [
renderer.media_type for renderer in self.schema_renderers
]
api_view_urls = self._api_view_urls
class APIRoot(views.APIView):
_ignore_model_permissions = True
renderer_classes = view_renderers
def get(self, request, *args, **kwargs):
if request.accepted_renderer.media_type in schema_media_types:
# Return a schema response.
schema = schema_generator.get_schema(request)
if schema is None:
raise exceptions.PermissionDenied()
return Response(schema)
# Return a plain {"name": "hyperlink"} response.
ret = OrderedDict()
namespace = request.resolver_match.namespace
for key, url_name in api_root_dict.items():
if namespace:
url_name = namespace + ':' + url_name
try:
ret[key] = reverse.reverse(url_name,
args=args,
kwargs=kwargs,
request=request,
format=kwargs.get(
'format', None))
except NoReverseMatch:
# Don't bail out if eg. no list routes exist, only detail routes.
continue
# In addition to what had been added, now add the APIView urls
for api_view_key in api_view_urls.keys():
url_name = api_view_urls[api_view_key].name
if namespace:
url_name = namespace + ':' + url_name
ret[api_view_key] = reverse.reverse(
url_name, request=request, format=kwargs.get('format'))
return response.Response(ret)
return APIRoot.as_view()
def get(self, request):
generator = SchemaGenerator(title="Title of Your Cool API")
schema = generator.get_schema(request=request)
return rest_framework.response.Response(schema)
def schema_view(request):
generator = SchemaGenerator(title='OST API')
return Response(generator.get_schema(request=request))
def get(self, request):
generator = SchemaGenerator(title='FamilySpace API')
schema = generator.get_schema(request=request, public=True)
return Response(schema)
def schema_view(request):
# Pass urlconf so only hr modules urls are registered
generator = SchemaGenerator(title='Jobs API', urlconf=('hr.urls'),)
return response.Response(generator.get_schema(request=request))
def get(self, request):
generator = SchemaGenerator(title='Pinestraw Project', version='1.0.0')
schema = generator.get_schema()
return Response(schema)
Including another URLconf
1. Import the include() function: from django.conf.urls import url, include
2. Add a URL to urlpatterns: url(r'^blog/', include('blog.urls'))
"""
from django.conf.urls import url, include
from rest_framework.routers import DefaultRouter
from rest_framework.schemas import SchemaGenerator
from snippets import views
# 注册viewsets到路由
router = DefaultRouter(trailing_slash=True)
router.register(r'snippets', views.SnippetViewSet)
router.register(r'users', views.UserViewSet)
schema_view = SchemaGenerator(title='Miya API')
# urlpatterns = [
# url(r'^', include(router.urls)),
# url(r'^schema/$', schema_view),
# ]
urlpatterns = [
url(r'^snippets/$', views.snippet_list),
url(r'^snippets/highlight/(?P<pk>[0-9]+)/$', views.snippet_list),
url(r'^snippets/(?P<pk>[0-9]+)/$', views.snippet_detail),
url(r'^users/$', views.user_list),
url(r'^users/(?P<pk>[0-9]+)/$', views.snippet_detail),
]
def test_4605_regression(self):
generator = SchemaGenerator()
prefix = generator.determine_path_prefix(
['/api/v1/items/', '/auth/convert-token/'])
assert prefix == '/'
def get(self, request):
generator = SchemaGenerator(title="Shuup API")
schema = generator.get_schema(request=request)
return Response(schema)
def schema_view(request):
generator = SchemaGenerator(title="PKDB Web API")
return Response(generator.get_schema(request=request))
def get(self, request):
generator = SchemaGenerator(title=title)
schema = generator.get_schema()
return Response(schema)
def schema_view(request):
"""
Swagger API documentation
"""
generator = SchemaGenerator(title="Videofront API")
return Response(generator.get_schema(request=request))
def get_api_root_view(self, schema_urls=None):
"""Create a class-based view to use as the API root.
Highly inspired by the base class. See details on the implementation
in the base class. The only difference is that registered view URLs
are added after the registered viewset URLs on this root API page.
Args:
schema_urls: A schema to use for the URLs.
Returns:
The view to use to display the root API page.
"""
api_root_dict = OrderedDict()
list_name = self.routes[0].name
for prefix, viewset, basename in self.registry:
api_root_dict[prefix] = list_name.format(basename=basename)
for pattern, view, name in self.view_registry:
api_root_dict[pattern] = name
view_renderers = list(api_settings.DEFAULT_RENDERER_CLASSES)
schema_media_types = []
if schema_urls and self.schema_title:
view_renderers += list(self.schema_renderers)
schema_generator = SchemaGenerator(title=self.schema_title,
patterns=schema_urls)
schema_media_types = [
renderer.media_type for renderer in self.schema_renderers
]
class APIRoot(views.APIView):
_ignore_model_permissions = True
renderer_classes = view_renderers
@staticmethod
def get(request, *args, **kwargs):
if request.accepted_renderer.media_type in schema_media_types:
# Return a schema response.
schema = schema_generator.get_schema(request)
if schema is None:
raise exceptions.PermissionDenied()
return Response(schema)
# Return a plain {"name": "hyperlink"} response.
ret = OrderedDict()
namespace = request.resolver_match.namespace
for key, url_name in api_root_dict.items():
if namespace:
url_name = namespace + ':' + url_name
try:
ret[key] = reverse(url_name,
args=args,
kwargs=kwargs,
request=request,
format=kwargs.get('format', None))
except NoReverseMatch:
# Don't bail out if eg. no list routes exist, only detail routes.
continue
return Response(ret)
return APIRoot.as_view()
def test_schema_for_regular_views(self):
"""
Ensure that schema generation works for ViewSet classes
with method limitation by Django CBV's http_method_names attribute
"""
generator = SchemaGenerator(title='Example API',
patterns=self.patterns)
request = factory.get('/example1/')
schema = generator.get_schema(Request(request))
expected = coreapi.Document(
url='http://testserver/example1/',
title='Example API',
content={
'example1': {
'list':
coreapi.Link(
url='/example1/',
action='get',
fields=[
coreapi.Field(
'page',
required=False,
location='query',
schema=coreschema.Integer(
title='Page',
description=
'A page number within the paginated result set.'
)),
coreapi.Field(
'page_size',
required=False,
location='query',
schema=coreschema.Integer(
title='Page size',
description=
'Number of results to return per page.')),
coreapi.Field(
'ordering',
required=False,
location='query',
schema=coreschema.String(
title='Ordering',
description=
'Which field to use when ordering the results.'
))
]),
'custom_list_action':
coreapi.Link(url='/example1/custom_list_action/',
action='get'),
'custom_list_action_multiple_methods': {
'read':
coreapi.Link(
url=
'/example1/custom_list_action_multiple_methods/',
action='get')
},
'read':
coreapi.Link(url='/example1/{id}/',
action='get',
fields=[
coreapi.Field('id',
required=True,
location='path',
schema=coreschema.String())
])
}
})
assert schema == expected
def get(self, request):
generator = SchemaGenerator(title='PowerAdmin API')
schema = generator.get_schema(request=request)
return Response(schema)
def get(self, request):
generator = SchemaGenerator(
title='API Documentation', urlconf='snippets.apiurls', url='/api/')
schema = generator.get_schema(request=request)
return Response(schema)
def get(self, request):
generator = SchemaGenerator(title="RDMO API",
patterns=urlpatterns,
url=request.path)
schema = generator.get_schema(request=request)
return Response(schema)
def get(self, request):
generator = SchemaGenerator()
schema = generator.get_schema(request=request)
return Response(schema)
def get(self, request):
generator = SchemaGenerator(title='Data Treat API',
url='/data-treat/api/',
urlconf='data_treat_api.urls')
schema = generator.get_schema(request=request)
return Response(schema)
