TMP: Convert some things to API docs with abuse

src/olympia/abuse/models.py

@@ -571,10 +571,18 @@ class AbuseReport(ModelBase):
         help_text='The add-on summary in the locale used by the client.',
     )
     addon_version = models.CharField(
-        default=None, max_length=255, blank=True, null=True
+        default=None,
+        max_length=255,
+        blank=True,
+        null=True,
+        help_text='The add-on version string.',
     )
     addon_signature = models.PositiveSmallIntegerField(
-        default=None, choices=ADDON_SIGNATURES.choices, blank=True, null=True
+        default=None,
+        choices=ADDON_SIGNATURES.choices,
+        blank=True,
+        null=True,
+        help_text=' The add-on signature state.',
     )
     application = models.PositiveSmallIntegerField(
         default=amo.FIREFOX.id, choices=amo.APPS_CHOICES, blank=True, null=True
@@ -586,14 +594,28 @@ class AbuseReport(ModelBase):
         default=None, max_length=255, blank=True, null=True
     )
     operating_system = models.CharField(
-        default=None, max_length=255, blank=True, null=True
+        default=None,
+        max_length=255,
+        blank=True,
+        null=True,
+        help_text="The client's operating system.",
     )
     operating_system_version = models.CharField(
-        default=None, max_length=255, blank=True, null=True
+        default=None,
+        max_length=255,
+        blank=True,
+        null=True,
+        help_text="The client's operating system version.",
+    )
+    install_date = models.DateTimeField(
+        default=None, blank=True, null=True, help_text='The add-on install date.'
     )
-    install_date = models.DateTimeField(default=None, blank=True, null=True)
     reason = models.PositiveSmallIntegerField(
-        default=None, choices=REASONS.choices, blank=True, null=True
+        default=None,
+        choices=REASONS.choices,
+        blank=True,
+        null=True,
+        help_text='The reason for the report.',
     )
     addon_install_origin = models.CharField(
         # Supposed to be an URL, but the scheme could be moz-foo: or something
@@ -604,6 +626,7 @@ class AbuseReport(ModelBase):
         max_length=255,
         blank=True,
         null=True,
+        help_text='The add-on install origin.',
     )
     addon_install_method = models.PositiveSmallIntegerField(
         default=None,
@@ -633,9 +656,14 @@ class AbuseReport(ModelBase):
         max_length=255,
         blank=True,
         null=True,
+        help_text='The add-on install source URL.',
     )
     report_entry_point = models.PositiveSmallIntegerField(
-        default=None, choices=REPORT_ENTRY_POINTS.choices, blank=True, null=True
+        default=None,
+        choices=REPORT_ENTRY_POINTS.choices,
+        blank=True,
+        null=True,
+        help_text='Where and in what context was the report sent from.',
     )
     location = models.PositiveSmallIntegerField(
         default=None,
@@ -659,14 +687,14 @@ class AbuseReport(ModelBase):
         choices=ILLEGAL_CATEGORIES.choices,
         blank=True,
         null=True,
-        help_text='Type of illegal content',
+        help_text='The type of illegal content - only required when the reason is set to illegal.',
     )
     illegal_subcategory = models.PositiveSmallIntegerField(
         default=None,
         choices=ILLEGAL_SUBCATEGORIES.choices,
         blank=True,
         null=True,
-        help_text='Specific violation of illegal content',
+        help_text='The specific violation - only required when the reason is set to illegal',
     )
 
     objects = AbuseReportManager()

src/olympia/abuse/serializers.py

@@ -47,6 +47,7 @@ class BaseAbuseReportSerializer(AMOModelSerializer):
         allow_blank=True,
         max_length=10000,
         error_messages=error_messages,
+        help_text='The body/content of the abuse report (required).',
     )
     lang = serializers.CharField(
         required=False,
@@ -164,16 +165,21 @@ def create(self, validated_data):
 
 class AddonAbuseReportSerializer(BaseAbuseReportSerializer):
     addon = serializers.SerializerMethodField(
-        help_text='The add-on reported for abuse.'
+        help_text='The id, slug, or guid of the add-on to report for abuse (required).',
     )
     app = ReverseChoiceField(
         choices=list((v.id, k) for k, v in amo.APPS.items()),
         required=False,
         source='application',
+        help_text='The application used by the client.',
     )
     appversion = serializers.CharField(
-        required=False, source='application_version', max_length=255
+        required=False,
+        source='application_version',
+        max_length=255,
+        help_text='The application version used by the client.',
     )
+
     report_entry_point = ReverseChoiceField(
         choices=list(AbuseReport.REPORT_ENTRY_POINTS.api_choices),
         required=False,
@@ -183,16 +189,19 @@ class AddonAbuseReportSerializer(BaseAbuseReportSerializer):
         choices=list(AbuseReport.ADDON_INSTALL_METHODS.api_choices),
         required=False,
         allow_null=True,
+        help_text='The add-on install method.',
     )
     addon_install_source = ReverseChoiceField(
         choices=list(AbuseReport.ADDON_INSTALL_SOURCES.api_choices),
         required=False,
         allow_null=True,
+        help_text='The add-on install source.',
     )
     addon_signature = ReverseChoiceField(
         choices=list(AbuseReport.ADDON_SIGNATURES.api_choices),
         required=False,
         allow_null=True,
+        help_text='The add-on signature state.',
     )
     reason = ReverseChoiceField(
         # For add-ons we use the full list of reasons as choices.

src/olympia/abuse/views.py

@@ -10,6 +10,7 @@
 from django.template.response import TemplateResponse
 from django.utils.encoding import force_bytes
 
+from drf_spectacular.utils import extend_schema, extend_schema_view
 from rest_framework import status
 from rest_framework.decorators import (
     api_view,
@@ -87,6 +88,16 @@ def get_target_object(self):
         return self.target_object
 
 
+@extend_schema_view(
+    create=extend_schema(
+        description=(
+            'The following API endpoint allows an abuse report to be submitted '
+            'for an Add-on, either listed on https://addons.mozilla.org or not. '
+            'Authentication is not required, but is recommended '
+            'so reports can be responded to if necessary.'
+        ),
+    )
+)
 class AddonAbuseViewSet(AbuseTargetMixin, CreateModelMixin, GenericViewSet):
     permission_classes = []
     serializer_class = AddonAbuseReportSerializer

src/olympia/api/urls.py

@@ -1,7 +1,11 @@
 from django.conf import settings
 from django.urls import include, re_path
 
-from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerSplitView
+from drf_spectacular.views import (
+    SpectacularAPIView,
+    SpectacularRedocView,
+    SpectacularSwaggerSplitView,
+)
 
 from olympia.accounts.urls import accounts_v3, accounts_v4, auth_urls
 from olympia.addons.api_urls import addons_v3, addons_v4, addons_v5

src/olympia/lib/settings_base.py

@@ -1562,10 +1562,10 @@ def read_only_mode(env):
 SOCKET_LABS_SERVER_ID = env('SOCKET_LABS_SERVER_ID', default=None)
 
 SPECTACULAR_SETTINGS = {
-    'TITLE': 'Your Project API',
-    'DESCRIPTION': 'Your project description',
-    'VERSION': '1.0.0',
-    'SERVE_INCLUDE_SCHEMA': False,
+    'TITLE': 'AMO API',
+    'DESCRIPTION': 'Addons Server API Documentation',
+    'SERVE_INCLUDE_SCHEMA': True,
+    'SERVE_PERMISSIONS': ['rest_framework.permissions.AllowAny'],
     # load swagger/redoc assets via collectstatic assets
     # rather than via the CDN
     'SWAGGER_UI_DIST': 'SIDECAR',

src/olympia/ratings/views.py

@@ -1,6 +1,7 @@
 from django.db.models import Prefetch, Q
 from django.utils.encoding import force_str
 
+from drf_spectacular.utils import extend_schema, extend_schema_view
 from rest_framework import serializers
 from rest_framework.decorators import action
 from rest_framework.exceptions import NotAuthenticated, ParseError, PermissionDenied
@@ -106,6 +107,22 @@ class RatingFlagThrottle(GranularUserRateThrottle):
     scope = 'user_rating_flag_throttle'
 
 
+@extend_schema_view(
+    list=extend_schema(
+        description=(
+            """
+            This endpoint allows you to fetch ratings for a given add-on or user. Either
+            ``addon`` or ``user`` query parameters are required, and they can be
+            combined together.
+
+            When ``addon``, ``user`` and ``version`` are passed on the same request,
+            ``page_size`` will automatically be set to ``1``, since an user can only post
+            one rating per version of a given add-on. This can be useful to find out if a
+            user has already posted a rating for the current version of an add-on.
+            """
+        ),
+    ),
+)
 class RatingViewSet(AddonChildMixin, ModelViewSet):
     serializer_class = RatingSerializer
     permission_classes = [