minor updates to satnogs-db-api-client

With the new drf-spectacular generated schema, need to add nulltype to the list of requirements to install

update copyright dates

Improve examples and client generated docs via drf-spectacular

Signed-off-by: Corey Shields <cshields@gmail.com>

db/api/views.py

@@ -2,7 +2,8 @@
 from django.core.files.base import ContentFile
 from django.db.models import F
 from drf_spectacular.types import OpenApiTypes
-from drf_spectacular.utils import OpenApiParameter, extend_schema, extend_schema_view
+from drf_spectacular.utils import OpenApiExample, OpenApiParameter, extend_schema, \
+    extend_schema_view
 from rest_framework import mixins, status, viewsets
 from rest_framework.parsers import FileUploadParser, FormParser, MultiPartParser
 from rest_framework.permissions import IsAuthenticated
@@ -14,9 +15,12 @@ from db.api import filters, pagination, serializers
 from db.api.perms import SafeMethodsWithPermission
 from db.api.renderers import BrowserableJSONLDRenderer, JSONLDRenderer
 from db.base.helpers import gridsquare
-from db.base.models import Artifact, DemodData, LatestTleSet, Mode, Satellite, Transmitter
+from db.base.models import SATELLITE_STATUS, SERVICE_TYPE, TRANSMITTER_STATUS, TRANSMITTER_TYPE, \
+    Artifact, DemodData, LatestTleSet, Mode, Satellite, Transmitter
 from db.base.tasks import update_satellite
 
+ISS_EXAMPLE = OpenApiExample('25544 (ISS)', value=25544)
+
 
 @extend_schema_view(
     retrieve=extend_schema(
@@ -54,14 +58,15 @@ class ModeViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R0901
                 type=bool
             ),
             OpenApiParameter(
-                name='norad_cat_id',
+                name='status',
-                description='Select a satellite by its NORAD-assigned identifier'
+                description='Filter by satellite status: ' + ' '.join(SATELLITE_STATUS),
+                required=False,
+                type=OpenApiTypes.STR
             ),
             OpenApiParameter(
-                name='status',
+                name='norad_cat_id',
-                description='Filter satellites by their operational status',
+                description='Select a satellite by its NORAD-assigned identifier',
-                required=False,
+                examples=[ISS_EXAMPLE],
-                type=bool
             ),
         ],
     ),
@@ -72,10 +77,11 @@ class ModeViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R0901
                 'norad_cat_id',
                 OpenApiTypes.INT64,
                 OpenApiParameter.PATH,
-                description='Select a satellite by its NORAD-assigned identifier'
+                description='Select a satellite by its NORAD-assigned identifier',
+                examples=[ISS_EXAMPLE],
             ),
         ],
-    )
+    ),
 )
 class SatelliteViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R0901
     """
@@ -90,6 +96,38 @@ class SatelliteViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R0901
     lookup_field = 'norad_cat_id'
 
 
+@extend_schema_view(
+    list=extend_schema(
+        parameters=[
+            OpenApiParameter(
+                name='satellite__norad_cat_id',
+                description='NORAD ID of a satellite to filter telemetry data for',
+                examples=[ISS_EXAMPLE],
+            ),
+            OpenApiParameter(
+                name='status',
+                description='Filter by transmitter status: ' + ' '.join(TRANSMITTER_STATUS),
+                required=False,
+                type=OpenApiTypes.STR,
+                examples=[OpenApiExample('active', value='\'active\'')]
+            ),
+            OpenApiParameter(
+                name='service',
+                description='Filter by transmitter service: ' + ' '.join(SERVICE_TYPE),
+                required=False,
+                type=OpenApiTypes.STR,
+                examples=[OpenApiExample('Amateur', value='\'Amateur\'')]
+            ),
+            OpenApiParameter(
+                name='type',
+                description='Filter by transmitter type: ' + ' '.join(TRANSMITTER_TYPE),
+                required=False,
+                type=OpenApiTypes.STR,
+                examples=[OpenApiExample('Transmitter', value='\'Transmitter\'')]
+            ),
+        ],
+    ),
+)
 class TransmitterViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R0901
     """
     Read-only view into the Transmitter entities in the SatNOGS DB database.
@@ -155,7 +193,8 @@ class LatestTleSetViewSet(viewsets.ReadOnlyModelViewSet):  # pylint: disable=R09
             ),
             OpenApiParameter(
                 name='satellite',
-                description='NORAD ID of a satellite to filter telemetry data for'
+                description='NORAD ID of a satellite to filter telemetry data for',
+                examples=[ISS_EXAMPLE],
             ),
             OpenApiParameter(name='transmitter', description='Not currently in use'),
         ],

db/settings.py

@@ -283,22 +283,17 @@ REST_FRAMEWORK = {
     ],
     'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend', ),
     'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+    'FORMAT_SUFFIX_KWARG': 'format',
 }
 
 SPECTACULAR_SETTINGS = {
-    # path prefix is used for tagging the discovered operations.
-    # use '/api/v[0-9]' for tagging apis like '/api/v1/albums' with ['albums']
     'SCHEMA_PATH_PREFIX': r'/api',
     'DEFAULT_GENERATOR_CLASS': 'drf_spectacular.generators.SchemaGenerator',
 
     # Configuration for serving the schema with SpectacularAPIView
     'SERVE_URLCONF': None,
-
-    # complete public schema or a subset based on the requesting user
     'SERVE_PUBLIC': True,
-
+    'SERVE_INCLUDE_SCHEMA': False,
-    # is the
-    'SERVE_INCLUDE_SCHEMA': True,
     'SERVE_PERMISSIONS': ['rest_framework.permissions.AllowAny'],
 
     # available SwaggerUI configuration parameters
@@ -309,29 +304,22 @@ SPECTACULAR_SETTINGS = {
         'displayOperationId': True,
     },
 
-    # available SwaggerUI versions: https://github.com/swagger-api/swagger-ui/releases
+    # we pull swagger-ui in via npm, as opposed to using their cdn
     'SWAGGER_UI_DIST': STATIC_URL + 'lib/swagger-ui-dist',
     'SWAGGER_UI_FAVICON_HREF': STATIC_URL + 'favicon.ico',
     'TITLE': 'SatNOGS DB',
     'DESCRIPTION': 'SatNOGS DB is a crowdsourced database of details about orbital \
                     satellites and data collected from them.',
     'TOS': None,
-
-    # Optional: MAY contain "name", "url", "email"
     'CONTACT': {
         'name': 'SatNOGS Developer Chat',
         'url': 'https://riot.im/app/#/room/#satnogs-dev:matrix.org'
     },
-
-    # Optional: MUST contain "name", MAY contain URL
     'LICENSE': {
         'name': 'AGPL 3.0',
         'url': 'https://www.gnu.org/licenses/agpl-3.0.html'
     },
     'VERSION': '1.1',
-
-    # Optional list of servers.
-    # Each entry MUST contain "url", MAY contain "description", "variables"
     'SERVERS': [
         {
             'url': 'https://db-dev.satnogs.org',
@@ -341,14 +329,8 @@ SPECTACULAR_SETTINGS = {
             'description': 'Production server'
         }
     ],
-
+    'PREPROCESSING_HOOKS': ['drf_spectacular.hooks.preprocess_exclude_path_format'],
-    # Postprocessing functions that run at the end of schema generation.
-    # must satisfy interface result = hook(generator, request, public, result)
     'POSTPROCESSING_HOOKS': ['drf_spectacular.hooks.postprocess_schema_enums'],
-
-    # Function that returns a mocked request for view processing. For CLI usage
-    # original_request will be None.
-    # interface: request = build_mock_request(method, path, view, original_request, **kwargs)
     'GET_MOCK_REQUEST': 'drf_spectacular.plumbing.build_mock_request',
 
     # Tags defined in the global scope
@@ -392,8 +374,6 @@ SPECTACULAR_SETTINGS = {
                             and Transponders'
         },
     ],
-
-    # Optional: MUST contain 'url', may contain "description"
     'EXTERNAL_DOCS': {
         'url': 'https://wiki.satnogs.org',
         'description': 'SatNOGS Wiki'

requirements.txt

@@ -33,7 +33,7 @@ django-shortuuidfield==0.1.3
 django-widget-tweaks==1.4.8
 djangorestframework==3.12.2
 dnspython==1.16.0
-drf-spectacular==0.12.0
+drf-spectacular==0.13.0
 ecdsa==0.14.1
 enum34==1.1.10
 eventlet==0.29.1

satnogs-db-api-client/README.md

@@ -7,4 +7,4 @@ This is the API client.
 ## License
 
 [![license](https://img.shields.io/badge/license-AGPL%203.0-6672D8.svg)](LICENSE)
-[![Libre Space Foundation](https://img.shields.io/badge/%C2%A9%202014--2019-Libre%20Space%20Foundation-6672D8.svg)](https://librespacefoundation.org/)
+[![Libre Space Foundation](https://img.shields.io/badge/%C2%A9%202014--2021-Libre%20Space%20Foundation-6672D8.svg)](https://librespacefoundation.org/)

satnogs-db-api-client/openapi-generator-config.json

@@ -10,6 +10,6 @@
     "perlModuleName": "satnogsdbapiclient",
     "phpInvokerPackage": "satnogsdbapiclient",
     "pythonPackageName": "satnogsdbapiclient",
-    "licenseInfo": "Copyright (C) 2020 Libre Space Foundation <https://libre.space/>",
+    "licenseInfo": "Copyright (C) 2021 Libre Space Foundation <https://libre.space/>",
     "licenseUrl": "https://www.gnu.org/licenses/agpl-3.0.html"
 }

satnogs-db-api-client/setup.cfg

@@ -26,6 +26,7 @@ install_requires =
     urllib3~=1.25.0
     six~=1.15.0
     certifi
+    nulltype~=2.3.0
     python-dateutil~=2.8.0
 
 # See the docstring in versioneer.py for instructions. Note that you must

setup.cfg

@@ -53,7 +53,7 @@ install_requires =
     django_compressor~=2.4.0
     # API
     djangorestframework~=3.12.0
-    drf-spectacular~=0.12.0
+    drf-spectacular~=0.13.0
     Markdown~=3.3.0
     django-filter~=2.4.0
     # Astronomy