Fix API documentation rendering (#15116) (#15726)

* Fix API documentation rendering related #15116

* Fix tests and formatting issues #15116

awx/api/generics.py

@@ -162,9 +162,9 @@ def get_view_description(view, html=False):
 
 def get_default_schema():
     if settings.SETTINGS_MODULE == 'awx.settings.development':
-        from awx.api.swagger import AutoSchema
+        from awx.api.swagger import schema_view
 
-        return AutoSchema()
+        return schema_view
     else:
         return views.APIView.schema
 

awx/api/swagger.py

@@ -1,62 +1,54 @@
 import warnings
 
 from rest_framework.permissions import AllowAny
-from rest_framework.schemas import SchemaGenerator, AutoSchema as DRFAuthSchema
-
-from drf_yasg.views import get_schema_view
 from drf_yasg import openapi
+from drf_yasg.inspectors import SwaggerAutoSchema
+from drf_yasg.views import get_schema_view
 
 
-class SuperUserSchemaGenerator(SchemaGenerator):
-    def has_view_permissions(self, path, method, view):
-        #
-        # Generate the Swagger schema as if you were a superuser and
-        # permissions didn't matter; this short-circuits the schema path
-        # discovery to include _all_ potential paths in the API.
-        #
-        return True
+class CustomSwaggerAutoSchema(SwaggerAutoSchema):
+    """Custom SwaggerAutoSchema to add swagger_topic to tags."""
 
-
-class AutoSchema(DRFAuthSchema):
-    def get_link(self, path, method, base_url):
-        link = super(AutoSchema, self).get_link(path, method, base_url)
+    def get_tags(self, operation_keys=None):
+        tags = []
         try:
-            serializer = self.view.get_serializer()
+            if hasattr(self.view, 'get_serializer'):
+                serializer = self.view.get_serializer()
+            else:
+                serializer = None
         except Exception:
             serializer = None
             warnings.warn(
                 '{}.get_serializer() raised an exception during '
                 'schema generation. Serializer fields will not be '
-                'generated for {} {}.'.format(self.view.__class__.__name__, method, path)
+                'generated for {}.'.format(self.view.__class__.__name__, operation_keys)
             )
-
-        link.__dict__['deprecated'] = getattr(self.view, 'deprecated', False)
-
-        # auto-generate a topic/tag for the serializer based on its model
         if hasattr(self.view, 'swagger_topic'):
-            link.__dict__['topic'] = str(self.view.swagger_topic).title()
+            tags.append(str(self.view.swagger_topic).title())
         elif serializer and hasattr(serializer, 'Meta'):
-            link.__dict__['topic'] = str(serializer.Meta.model._meta.verbose_name_plural).title()
+            tags.append(str(serializer.Meta.model._meta.verbose_name_plural).title())
         elif hasattr(self.view, 'model'):
-            link.__dict__['topic'] = str(self.view.model._meta.verbose_name_plural).title()
+            tags.append(str(self.view.model._meta.verbose_name_plural).title())
         else:
-            warnings.warn('Could not determine a Swagger tag for path {}'.format(path))
-        return link
+            tags = ['api']  # Fallback to default value
 
-    def get_description(self, path, method):
-        setattr(self.view.request, 'swagger_method', method)
-        description = super(AutoSchema, self).get_description(path, method)
-        return description
+        if not tags:
+            warnings.warn(f'Could not determine tags for {self.view.__class__.__name__}')
+        return tags
+
+    def is_deprecated(self):
+        """Return `True` if this operation is to be marked as deprecated."""
+        return getattr(self.view, 'deprecated', False)
 
 
 schema_view = get_schema_view(
     openapi.Info(
-        title="Snippets API",
-        default_version='v1',
-        description="Test description",
-        terms_of_service="https://www.google.com/policies/terms/",
-        contact=openapi.Contact(email="contact@snippets.local"),
-        license=openapi.License(name="BSD License"),
+        title='AWX API',
+        default_version='v2',
+        description='AWX API Documentation',
+        terms_of_service='https://www.google.com/policies/terms/',
+        contact=openapi.Contact(email='contact@snippets.local'),
+        license=openapi.License(name='Apache License'),
     ),
     public=True,
     permission_classes=[AllowAny],

awx/settings/defaults.py

@@ -387,6 +387,10 @@ REST_FRAMEWORK = {
     # 'URL_FORMAT_OVERRIDE': None,
 }
 
+SWAGGER_SETTINGS = {
+    'DEFAULT_AUTO_SCHEMA_CLASS': 'awx.api.swagger.CustomSwaggerAutoSchema',
+}
+
 AUTHENTICATION_BACKENDS = ('awx.main.backends.AWXModelBackend',)
 
 # Enable / Disable HTTP Basic Authentication used in the API browser