def get(self, request, *args, **kwargs):
path = request.path
path = path[:request.path.find('/api-docs')]
apis = self.get_apis(path)
generator = DocumentationGenerator(for_user=request.user)
info = copy.deepcopy(rfs.SWAGGER_SETTINGS.get('info', {
'contact': {},
'description': '',
'license': {'name': ''},
'termsOfService': '',
'title': '',
'version': '',
}))
if 'version' not in info or info['version'] == '':
matches = version_re.search(path)
if matches is not None:
info['version'] = matches.groups()[0]
return Response({
'swagger': '2.0',
'basePath': path,
'paths': generator.generate(apis),
'definitions': generator.get_models(apis),
'info': info,
'tags': rfs.SWAGGER_SETTINGS.get('tags', [])
})
def test_get_allowed_methods(self):
"""
Tests a ModelViewSet's allowed methods. If the path includes something like {pk},
consider it an object view, otherwise, a list view
"""
from django.contrib.auth.models import User
class MyViewSet(ModelViewSet):
serializer_class = CommentSerializer
model = User
docgen = DocumentationGenerator()
# Test a list endpoint
allowed_methods = docgen.__get_allowed_methods__(
MyViewSet, '/api/endpoint')
self.assertEqual(2, len(allowed_methods))
self.assertIn('POST', allowed_methods)
self.assertIn('GET', allowed_methods)
# Test an object endpoint
allowed_methods = docgen.__get_allowed_methods__(
MyViewSet, '/api/endpoint/{pk}')
self.assertEqual(4, len(allowed_methods))
self.assertIn('POST', allowed_methods)
self.assertIn('PATCH', allowed_methods)
self.assertIn('DELETE', allowed_methods)
self.assertIn('GET', allowed_methods)
def test_get_allowed_methods(self):
"""
Tests a ModelViewSet's allowed methods. If the path includes something like {pk},
consider it an object view, otherwise, a list view
"""
from django.contrib.auth.models import User
class MyViewSet(ModelViewSet):
serializer_class = CommentSerializer
model = User
docgen = DocumentationGenerator()
# Test a list endpoint
allowed_methods = docgen.__get_allowed_methods__(MyViewSet, '/api/endpoint')
self.assertEqual(2, len(allowed_methods))
self.assertIn('POST', allowed_methods)
self.assertIn('GET', allowed_methods)
# Test an object endpoint
allowed_methods = docgen.__get_allowed_methods__(MyViewSet, '/api/endpoint/{pk}')
self.assertEqual(4, len(allowed_methods))
self.assertIn('POST', allowed_methods)
self.assertIn('PATCH', allowed_methods)
self.assertIn('DELETE', allowed_methods)
self.assertIn('GET', allowed_methods)
def test_build_body_parameters(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
docgen = DocumentationGenerator()
params = docgen.__build_body_parameters__(SerializedAPI)
self.assertEqual('CommentSerializer', params['name'])
def test_build_form_parameters(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
docgen = DocumentationGenerator()
params = docgen.__build_form_parameters__(SerializedAPI, 'POST')
self.assertEqual(len(CommentSerializer().get_fields()), len(params))
def test_build_body_parameters(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
docgen = DocumentationGenerator()
params = docgen.__build_body_parameters__(SerializedAPI)
self.assertEqual('CommentSerializer', params['name'])
def test_build_form_parameters(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
docgen = DocumentationGenerator()
params = docgen.__build_form_parameters__(SerializedAPI, 'POST')
self.assertEqual(len(CommentSerializer().get_fields()), len(params))
def get(self, request, version=None, swagger_config_name=None):
self.check_permission(request, swagger_config_name)
paths = self.get_paths()
generator = DocumentationGenerator(
for_user=request.user,
config=self.config,
request=request
)
return Response(generator.get_root(paths))
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apis': generator.generate(apis),
'models': generator.get_models(apis),
'basePath': self.api_full_uri.rstrip('/'),
})
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apis': generator.generate(apis),
'models': generator.get_models(apis),
'basePath': self.api_full_uri,
})
def test_get_method_generic_api_view(self):
class MyListView(ListCreateAPIView):
"""
My comment
"""
pass
generator = DocumentationGenerator()
method_docs = generator.__get_method_docs__(MyListView(), 'POST')
self.assertEqual("My comment", method_docs)
def get(self, request, path, *args, **kwargs):
apis = self.get_apis_for_resource(path)
generator = DocumentationGenerator(for_user=request.user)
return Response({
'apiVersion': rfs.SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': self.api_full_uri.rstrip('/'),
'resourcePath': '/' + path,
'apis': generator.generate(apis),
'models': generator.get_models(apis),
})
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apiVersion': SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': get_full_base_path(request),
'resourcePath': path,
'apis': generator.generate(apis),
'models': generator.get_models(apis),
})
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apiVersion': SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
"resourcePath": "/{}".format(path),
'apis': generator.generate(apis),
'models': generator.get_models(apis),
'basePath': self.api_full_uri.rstrip('/'),
})
def test_get_serializer_set(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
urlparser = UrlParser()
url_patterns = patterns('', url(r'my-api/', SerializedAPI.as_view()))
apis = urlparser.get_apis(url_patterns)
docgen = DocumentationGenerator()
serializers = docgen.__get_serializer_set__(apis)
self.assertIn(CommentSerializer, serializers)
def test_get_method_generic_api_view(self):
class MyListView(ListCreateAPIView):
"""
My comment
"""
pass
generator = DocumentationGenerator()
method_docs = generator.__get_method_docs__(MyListView(), 'POST')
self.assertEqual("My comment", method_docs)
def test_get_serializer_set(self):
class SerializedAPI(ListCreateAPIView):
serializer_class = CommentSerializer
urlparser = UrlParser()
url_patterns = patterns('', url(r'my-api/', SerializedAPI.as_view()))
apis = urlparser.get_apis(url_patterns)
docgen = DocumentationGenerator()
serializers = docgen.__get_serializer_set__(apis)
self.assertIn(CommentSerializer, serializers)
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apiVersion': SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
"resourcePath": "/{}".format(path),
'apis': generator.generate(apis),
'models': generator.get_models(apis),
'basePath': self.api_full_uri.rstrip('/'),
})
def test_get_operations_with_no_methods(self):
class AnAPIView(APIView):
pass
api = {
'path': 'a-path/',
'callback': AnAPIView,
'pattern': patterns('')
}
docgen = DocumentationGenerator()
operations = docgen.__get_operations__(api)
self.assertEqual([], operations)
def test_get_method_docs(self):
class TestApiView(APIView):
def get(self, *args):
"""
Here are my comments
"""
pass
generator = DocumentationGenerator()
docs_get = generator.__get_method_docs__(TestApiView(), 'GET')
self.assertEqual("Here are my comments", docs_get)
def test_get_method_docs(self):
class TestApiView(APIView):
def get(self, *args):
"""
Here are my comments
"""
pass
generator = DocumentationGenerator()
docs_get = generator.__get_method_docs__(TestApiView(), 'GET')
self.assertEqual("Here are my comments", docs_get)
def test_strip_params_from_docstring(self):
class AnAPIView(APIView):
"""
My comments are here
param -- my param
"""
pass
docgen = DocumentationGenerator()
docstring = docgen.__strip_params_from_docstring__(trim_docstring(AnAPIView.__doc__))
self.assertEqual("My comments are here<br/><br/>", docstring)
def get(self, request, path):
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return Response({
'apiVersion': rfs.SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': self.api_full_uri.rstrip('/'),
'resourcePath': '/' + path,
'apiCustomHeaders': rfs.SWAGGER_SETTINGS.get('custom_headers', {}),
'apis': generator.generate(apis),
'models': generator.get_models(apis),
})
def get(self, request, path, *args, **kwargs):
apis = self.get_apis_for_resource(path)
generator = DocumentationGenerator(for_user=request.user)
return Response(
{
"apiVersion": rfs.SWAGGER_SETTINGS.get("api_version", ""),
"swaggerVersion": "1.2",
"basePath": self.api_full_uri.rstrip("/"),
"resourcePath": "/" + path,
"apis": generator.generate(apis),
"models": generator.get_models(apis),
}
)
def test_strip_params_from_docstring(self):
class AnAPIView(APIView):
"""
My comments are here
param -- my param
"""
pass
docgen = DocumentationGenerator()
docstring = docgen.__strip_params_from_docstring__(trim_docstring(AnAPIView.__doc__))
self.assertEqual("My comments are here<br/>", docstring)
def get_api_declaration(self, path):
api_full_uri = SWAGGER_SETTINGS.get('api_full_uri')
apis = self.get_api_for_resource(path)
generator = DocumentationGenerator()
return {
'apiVersion': SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': api_full_uri.rstrip('/'),
'resourcePath': '/' + path,
'apis': generator.generate(apis),
'models': generator.get_models(apis),
}
def test_get_operations_with_no_methods(self):
class AnAPIView(APIView):
pass
api = {
'path': 'a-path/',
'callback': AnAPIView,
'pattern': patterns('')
}
docgen = DocumentationGenerator()
operations = docgen.__get_operations__(api)
self.assertEqual([], operations)
def get_api_declaration(self, path, urlconf):
api_full_uri = SWAGGER_SETTINGS.get('api_full_uri')
apis = self.get_api_for_resource(path, urlconf=urlconf)
generator = DocumentationGenerator()
return {
'apiVersion': SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': api_full_uri.rstrip('/'),
'resourcePath': '/' + path,
'apis': generator.generate(apis),
'models': generator.get_models(apis),
}
def test_get_operations(self):
class AnAPIView(APIView):
def post(self, *args, **kwargs):
pass
api = {
'path': 'a-path/',
'callback': AnAPIView,
'pattern': patterns('')
}
docgen = DocumentationGenerator()
operations = docgen.__get_operations__(api)
self.assertEqual('POST', operations[0]['httpMethod'])
def test_get_operations(self):
class AnAPIView(APIView):
def post(self, *args, **kwargs):
pass
api = {
'path': 'a-path/',
'callback': AnAPIView,
'pattern': patterns('')
}
docgen = DocumentationGenerator()
operations = docgen.__get_operations__(api)
self.assertEqual('POST', operations[0]['httpMethod'])
def get(self, request, path):
apis = self.get_api_for_resource(path)
apis = [api for api in apis
if self.handle_resource_access(request, api['pattern'])]
generator = DocumentationGenerator()
return Response({
'apiVersion': rfs.SWAGGER_SETTINGS.get('api_version', ''),
'swaggerVersion': '1.2',
'basePath': self.api_full_uri.rstrip('/'),
'resourcePath': '/' + path,
'apis': generator.generate(apis),
'models': generator.get_models(apis),
})
def test_build_form_parameters_allowable_values(self):
class MySerializer(serializers.Serializer):
content = serializers.CharField(max_length=200, min_length=10, default="Vandalay Industries")
a_read_only_field = serializers.BooleanField(read_only=True)
class MyAPIView(ListCreateAPIView):
serializer_class = MySerializer
docgen = DocumentationGenerator()
params = docgen.__build_form_parameters__(MyAPIView, 'POST')
self.assertEqual(1, len(params)) # Read only field is ignored
param = params[0]
self.assertEqual('content', param['name'])
self.assertEqual('form', param['paramType'])
self.assertEqual(True, param['required'])
self.assertEqual(200, param['allowableValues']['max'])
self.assertEqual(10, param['allowableValues']['min'])
self.assertEqual('Vandalay Industries', param['defaultValue'])
def test_build_form_parameters_allowable_values(self):
class MySerializer(serializers.Serializer):
content = serializers.CharField(max_length=200, min_length=10, default="Vandalay Industries")
a_read_only_field = serializers.BooleanField(read_only=True)
class MyAPIView(ListCreateAPIView):
serializer_class = MySerializer
docgen = DocumentationGenerator()
params = docgen.__build_form_parameters__(MyAPIView, 'POST')
self.assertEqual(1, len(params)) # Read only field is ignored
param = params[0]
self.assertEqual('content', param['name'])
self.assertEqual('form', param['paramType'])
self.assertEqual(True, param['required'])
self.assertEqual(200, param['allowableValues']['max'])
self.assertEqual(10, param['allowableValues']['min'])
self.assertEqual('Vandalay Industries', param['defaultValue'])
def test_strip_params_from_docstring_multiline(self):
class TestView(APIView):
"""
Creates a new user.
Returns: token - auth token
email -- e-mail address
password -- password, optional
city -- city, optional
street -- street, optional
number -- house number, optional
zip_code -- zip code 10 chars, optional
phone -- phone number in US format (XXX-XXX-XXXX), optional
"""
pass
docgen = DocumentationGenerator()
docstring = docgen.__strip_params_from_docstring__(TestView.__doc__)
expected = 'Creates a new user.<br/>Returns: token - auth token<br/>'
self.assertEqual(expected, docstring)
def test_strip_params_from_docstring_multiline(self):
class TestView(APIView):
"""
Creates a new user.
Returns: token - auth token
email -- e-mail address
password -- password, optional
city -- city, optional
street -- street, optional
number -- house number, optional
zip_code -- zip code 10 chars, optional
phone -- phone number in US format (XXX-XXX-XXXX), optional
"""
pass
docgen = DocumentationGenerator()
docstring = docgen.__strip_params_from_docstring__(TestView.__doc__)
expected = 'Creates a new user.<br/>Returns: token - auth token<br/>'
self.assertEqual(expected, docstring)
def get(self, request, *args, **kwargs):
apis = []
resources = self.get_resources()
for path in resources:
apis.append(
self.get_api_for_resource(path)
)
generator = DocumentationGenerator()
#parameters = generator.get_models(apis)
tags = {}
paths = {}
# TODO: reformat the contents that come from generator, don't
# post-process it here.
for path in generator.generate(apis):
mypath = {}
try:
tag = path['path'].split('/')[2]
except IndexError:
tag = None
for operation in path.get('operations', []):
# {
# 'parameters': [
# {'name': 'cigar', 'paramType': 'form', 'required': True, 'type': 'string', 'description': ''},
# {'name': 'jambalaya', 'paramType': 'form', 'required': True, 'type': 'string', 'description': ''}
# ],
# 'nickname': u'Drop_Cigar_In_Jambalaya_POST',
# 'notes': u'<p>Make a cigar jambalaya</p>',
# 'summary': u'Make a cigar jambalaya',
# 'type': 'CigarJambalayaSerializer',
# 'method': 'POST'
# }",
responses = {}
response_messages = operation.get('responseMessages', [])
if len(response_messages) == 0:
responses['default'] = {'description': 'Unknown'}
for response in response_messages:
responses[response['code']] = {
'description': response['message']
}
# TODO : this is almost certainly wrong
if response['responseModel']:
response[response['code']]['schema'] = {
"$ref": response['responseModel']
}
method = operation['method'].lower()
mypath[method] = {
#'debug': operation,
'description': operation['notes'],
'summary': operation['summary'],
'operationId': operation['nickname'],
'produces': [
'application/json'
],
'parameters': operation.get('parameters', []),
'responses': responses
}
if tag:
mypath[method]["tags"] = [tag]
if tag and tag not in tags:
tags[tag] = {
'name': tag,
'description': tag
}
paths[path['path']] = mypath
tag_list = []
for tag in tags:
tag_list.append(tag)
definitions = {}
securityDefinitions = {}
security = []
externalDocs = {}
full_uri = self.api_full_uri.rstrip('/').split('/')
scheme = full_uri[0].rstrip(':')
host = '/'.join(full_uri[2:3])
basePath = "/" + '/'.join(full_uri[3:])
return Response({
'swagger': '2.0',
'info': rfs.SWAGGER_SETTINGS['info'],
'host': host,
'basePath': basePath,
'schemes': [scheme],
'consumes': ['application/json'],
'produces': ['application/json'],
'paths': paths,
'definitions': definitions,
#'parameters': parameters,
'responses': {},
'securityDefinitions': securityDefinitions,
'security': security
})
def test_get_serializer_fields_api_with_no_serializer(self):
docgen = DocumentationGenerator()
fields = docgen.__get_serializer_fields__(None)
self.assertIsNone(fields)
def test_get_serializer_fields(self):
docgen = DocumentationGenerator()
fields = docgen.__get_serializer_fields__(CommentSerializer)
self.assertEqual(3, len(fields))
def test_get_description(self):
generator = DocumentationGenerator()
description = generator.__get_description__(MockApiView())
self.assertEqual('A Test View', description)
def test_get_serializer_fields(self):
docgen = DocumentationGenerator()
fields = docgen.__get_serializer_fields__(CommentSerializer)
self.assertEqual(3, len(fields))
def test_get_description(self):
generator = DocumentationGenerator()
description = generator.__get_description__(MockApiView())
self.assertEqual('A Test View', description)
def test_get_serializer_fields_api_with_no_serializer(self):
docgen = DocumentationGenerator()
fields = docgen.__get_serializer_fields__(None)
self.assertIsNone(fields)
def get(self, request, *args, **kwargs):
apis = []
resources = self.get_resources()
for path in resources:
apis.append(
self.get_api_for_resource(path)
)
generator = DocumentationGenerator()
tags = {}
paths = {}
# TODO: reformat the contents that come from generator, don't
# post-process it here.
for path in generator.generate(apis):
mypath = {}
try:
tag = path['path'].split('/')[2]
except IndexError:
tag = None
for operation in path.get('operations', []):
method = operation['method'].lower()
mypath[method] = {
'description': operation['notes'],
'summary': operation['summary'],
'produces': [
'application/json'
],
'responses': {
'default': {
'description': 'Unknown',
# 'schema': {
# '$ref': "#/definitions/ErrorModel"
# }
},
200: {
'description': 'Success'
}
}
}
if tag:
mypath[method]["tags"] = [tag]
if tag and tag not in tags:
tags[tag] = {
'name': tag,
'description': tag
}
paths[path['path']] = mypath
tag_list = []
for tag in tags:
tag_list.append(tag)
definitions = {}
parameters = {}
responses = {}
securityDefinitions = {}
security = []
tags = []
externalDocs = {}
full_uri = self.api_full_uri.rstrip('/').split('/')
scheme = full_uri[0].rstrip(':')
host = '/'.join(full_uri[2:3])
basePath = "/" + '/'.join(full_uri[3:])
return Response({
'swagger': '2.0',
'info': rfs.SWAGGER_SETTINGS['info'],
'host': host,
'basePath': basePath,
'schemes': [scheme],
'consumes': ['application/json'],
'produces': ['application/json'],
'paths': paths,
'definitions': definitions,
'parameters': parameters,
'responses': responses,
'securityDefinitions': securityDefinitions,
'security': security,
'tags': tag_list,
'externalDocs': externalDocs
# 'apiVersion': rfs.SWAGGER_SETTINGS.get('api_version', ''),
# 'swaggerVersion': '2.0',
# 'apis': generator.generate(apis),
# 'models': generator.get_models(apis),
})
