Improve openapi parameters

Author: banesullivan

django_large_image/rest/base.py

@@ -44,12 +44,17 @@ def get_style(self, request: Request):
                     style['min'] = bmin
                 if not utilities.param_nully(bmax):
                     style['max'] = bmax
-                palette = request.query_params.get('palette', None)
+                palette = request.query_params.get(
+                    'palette', request.query_params.get('cmap', None)
+                )
                 if not utilities.param_nully(palette):
                     style['palette'] = palette
                 nodata = request.query_params.get('nodata', None)
                 if not utilities.param_nully(nodata):
                     style['nodata'] = nodata
+                scheme = request.query_params.get('scheme', None)
+                if not utilities.param_nully:
+                    style['scheme'] = scheme
                 style = json.dumps(style)
         return style
 

django_large_image/rest/data.py

@@ -11,6 +11,15 @@
 from django_large_image.rest import params
 from django_large_image.rest.base import CACHE_TIMEOUT, LargeImageMixinBase
 
+thumbnail_summary = 'Returns thumbnail of full image.'
+thumbnail_parameters = [params.projection] + params.STYLE
+region_summary = 'Returns region tile binary.'
+region_parameters = [params.projection] + params.REGION
+pixel_summary = 'Returns single pixel.'
+pixel_parameters = [params.projection, params.left, params.top] + params.STYLE
+histogram_summary = 'Returns histogram'
+histogram_parameters = [params.projection] + params.HISTOGRAM
+
 
 class DataMixin(LargeImageMixinBase):
     def thumbnail(self, request: Request, pk: int = None, format: str = None) -> HttpResponse:
@@ -22,8 +31,8 @@ def thumbnail(self, request: Request, pk: int = None, format: str = None) -> Htt
     @method_decorator(cache_page(CACHE_TIMEOUT))
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns thumbnail of full image as PNG.',
-        manual_parameters=[params.projection] + params.STYLE,
+        operation_summary=thumbnail_summary,
+        manual_parameters=thumbnail_parameters,
     )
     @action(detail=False, url_path='thumbnail.png')
     def thumbnail_png(self, request: Request, pk: int = None) -> HttpResponse:
@@ -32,8 +41,8 @@ def thumbnail_png(self, request: Request, pk: int = None) -> HttpResponse:
     @method_decorator(cache_page(CACHE_TIMEOUT))
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns thumbnail of full image as JPEG.',
-        manual_parameters=[params.projection] + params.STYLE,
+        operation_summary=thumbnail_summary,
+        manual_parameters=thumbnail_parameters,
     )
     @action(detail=False, url_path='thumbnail.jpeg')
     def thumbnail_jpeg(self, request: Request, pk: int = None) -> HttpResponse:
@@ -75,35 +84,35 @@ def region(self, request: Request, pk: int = None, format: str = None) -> HttpRe
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns region tile binary from world coordinates in given EPSG as a tiled tif image.',
-        manual_parameters=[params.projection] + params.REGION,
+        operation_summary=region_summary,
+        manual_parameters=region_parameters,
     )
     @action(detail=False, url_path=r'region.tif')
     def region_tif(self, request: Request, pk: int = None) -> HttpResponse:
         return self.region(request, pk, format='tif')
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns region tile binary from world coordinates in given EPSG as a png image.',
-        manual_parameters=[params.projection] + params.REGION,
+        operation_summary=region_summary,
+        manual_parameters=region_parameters + params.STYLE,
     )
     @action(detail=False, url_path=r'region.png')
     def region_png(self, request: Request, pk: int = None) -> HttpResponse:
         return self.region(request, pk, format='png')
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns region tile binary from world coordinates in given EPSG as a jpeg image.',
-        manual_parameters=[params.projection] + params.REGION,
+        operation_summary=region_summary,
+        manual_parameters=region_parameters + params.STYLE,
     )
     @action(detail=False, url_path=r'region.jpeg')
     def region_jpeg(self, request: Request, pk: int = None) -> HttpResponse:
         return self.region(request, pk, format='jpeg')
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns single pixel.',
-        manual_parameters=[params.projection, params.left, params.top] + params.STYLE,
+        operation_summary=pixel_summary,
+        manual_parameters=pixel_parameters,
     )
     @action(detail=False)
     def pixel(self, request: Request, pk: int = None) -> Response:
@@ -115,8 +124,8 @@ def pixel(self, request: Request, pk: int = None) -> Response:
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns histogram',
-        manual_parameters=[params.projection] + params.HISTOGRAM,
+        operation_summary=histogram_summary,
+        manual_parameters=histogram_parameters,
     )
     @action(detail=False)
     def histogram(self, request: Request, pk: int = None) -> Response:
@@ -141,30 +150,67 @@ def histogram(self, request: Request, pk: int = None) -> Response:
 
 
 class DataDetailMixin(DataMixin):
+    @method_decorator(cache_page(CACHE_TIMEOUT))
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=thumbnail_summary,
+        manual_parameters=thumbnail_parameters,
+    )
     @action(detail=True, url_path='thumbnail.png')
     def thumbnail_png(self, request: Request, pk: int = None) -> HttpResponse:
         return super().thumbnail_png(request, pk)
 
+    @method_decorator(cache_page(CACHE_TIMEOUT))
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=thumbnail_summary,
+        manual_parameters=thumbnail_parameters,
+    )
     @action(detail=True, url_path='thumbnail.jpeg')
     def thumbnail_jpeg(self, request: Request, pk: int = None) -> HttpResponse:
         return super().thumbnail_jpeg(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=region_summary,
+        manual_parameters=region_parameters,
+    )
     @action(detail=True, url_path=r'region.tif')
     def region_tif(self, request: Request, pk: int = None) -> HttpResponse:
         return super().region_tif(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=region_summary,
+        manual_parameters=region_parameters + params.STYLE,
+    )
     @action(detail=True, url_path=r'region.png')
     def region_png(self, request: Request, pk: int = None) -> HttpResponse:
         return super().region_png(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=region_summary,
+        manual_parameters=region_parameters + params.STYLE,
+    )
     @action(detail=True, url_path=r'region.jpeg')
     def region_jpeg(self, request: Request, pk: int = None) -> HttpResponse:
         return super().region_jpeg(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=pixel_summary,
+        manual_parameters=pixel_parameters,
+    )
     @action(detail=True)
     def pixel(self, request: Request, pk: int = None) -> Response:
         return super().pixel(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=histogram_summary,
+        manual_parameters=histogram_parameters,
+    )
     @action(detail=True)
     def histogram(self, request: Request, pk: int = None) -> Response:
         return super().histogram(request, pk)

django_large_image/rest/metadata.py

@@ -7,12 +7,21 @@
 from django_large_image.rest import params
 from django_large_image.rest.base import LargeImageMixinBase
 
+metadata_summary = 'Returns tile metadata.'
+metadata_parameters = [params.projection]
+internal_metadata_summary = 'Returns additional known metadata about the tile source.'
+internal_metadata_parameters = [params.projection]
+bands_summary = 'Returns bands information.'
+bands_parameters = [params.projection]
+band_summary = 'Returns single band information.'
+band_parameters = [params.projection, params.band]
+
 
 class MetaDataMixin(LargeImageMixinBase):
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns tile metadata.',
-        manual_parameters=[params.projection],
+        operation_summary=metadata_summary,
+        manual_parameters=metadata_parameters,
     )
     @action(detail=False)
     def metadata(self, request: Request, pk: int = None) -> Response:
@@ -22,8 +31,8 @@ def metadata(self, request: Request, pk: int = None) -> Response:
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns additional known metadata about the tile source.',
-        manual_parameters=[params.projection],
+        operation_summary=internal_metadata_summary,
+        manual_parameters=internal_metadata_parameters,
     )
     @action(detail=False)
     def internal_metadata(self, request: Request, pk: int = None) -> Response:
@@ -33,8 +42,8 @@ def internal_metadata(self, request: Request, pk: int = None) -> Response:
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns bands information.',
-        manual_parameters=[params.projection],
+        operation_summary=bands_summary,
+        manual_parameters=bands_parameters,
     )
     @action(detail=False)
     def bands(self, request: Request, pk: int = None) -> Response:
@@ -44,11 +53,8 @@ def bands(self, request: Request, pk: int = None) -> Response:
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns single band information.',
-        manual_parameters=[
-            params.projection,
-            params.band,
-        ],
+        operation_summary=bands_summary,
+        manual_parameters=band_parameters,
     )
     @action(detail=False)
     def band(self, request: Request, pk: int = None) -> Response:
@@ -59,18 +65,38 @@ def band(self, request: Request, pk: int = None) -> Response:
 
 
 class MetaDataDetailMixin(MetaDataMixin):
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=metadata_summary,
+        manual_parameters=metadata_parameters,
+    )
     @action(detail=True)
     def metadata(self, request: Request, pk: int = None) -> Response:
         return super().metadata(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=internal_metadata_summary,
+        manual_parameters=internal_metadata_parameters,
+    )
     @action(detail=True)
     def internal_metadata(self, request: Request, pk: int = None) -> Response:
         return super().internal_metadata(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=bands_summary,
+        manual_parameters=bands_parameters,
+    )
     @action(detail=True)
     def bands(self, request: Request, pk: int = None) -> Response:
         return super().bands(request, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=bands_summary,
+        manual_parameters=band_parameters,
+    )
     @action(detail=True)
     def band(self, request: Request, pk: int = None) -> Response:
         return super().band(request, pk)

django_large_image/rest/params.py

@@ -42,8 +42,14 @@
     description='The value to map as no data (often made transparent).',
     type=openapi.TYPE_NUMBER,
 )
+scheme = openapi.Parameter(
+    'scheme',
+    openapi.IN_QUERY,
+    description='This is either ``linear`` (the default) or ``discrete``. If a palette is specified, ``linear`` uses a piecewise linear interpolation, and ``discrete`` uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).',
+    type=openapi.TYPE_STRING,
+)
 
-STYLE = [palette, band, vmin, vmax, nodata]
+STYLE = [palette, band, vmin, vmax, nodata, scheme]
 
 # Region Parameters
 left = openapi.Parameter(
@@ -63,7 +69,6 @@
     openapi.IN_QUERY,
     description='The projection/units of the region coordinates.',
     type=openapi.TYPE_STRING,
-    default='EPSG:4326',
 )
 
 REGION = [left, right, top, bottom, units]

django_large_image/rest/tiles.py

@@ -12,6 +12,11 @@
 from django_large_image.rest import params
 from django_large_image.rest.base import CACHE_TIMEOUT, LargeImageMixinBase
 
+tile_summary = 'Returns tile image binary.'
+tile_parameters = [params.projection, params.z, params.x, params.y] + params.STYLE
+tile_corners_summary = 'Returns bounds of a tile for a given x, y, z index.'
+tile_corners_parameters = [params.projection, params.z, params.x, params.y]
+
 
 class TilesMixin(LargeImageMixinBase):
     def tile(
@@ -29,8 +34,8 @@ def tile(
     @method_decorator(cache_page(CACHE_TIMEOUT))
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns tile image as a PNG.',
-        manual_parameters=[params.projection, params.z, params.x, params.y] + params.STYLE,
+        operation_summary=tile_summary,
+        manual_parameters=tile_parameters,
     )
     @action(detail=False, url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+).png')
     def tile_png(
@@ -46,8 +51,8 @@ def tile_png(
     @method_decorator(cache_page(CACHE_TIMEOUT))
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns tile image as a JPEG.',
-        manual_parameters=[params.projection, params.z, params.x, params.y] + params.STYLE,
+        operation_summary=tile_summary,
+        manual_parameters=tile_parameters,
     )
     @action(detail=False, url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+).jpeg')
     def tile_jpeg(
@@ -62,8 +67,8 @@ def tile_jpeg(
 
     @swagger_auto_schema(
         method='GET',
-        operation_summary='Returns bounds of a tile for a given x, y, z index.',
-        manual_parameters=[params.projection, params.z, params.x, params.y],
+        operation_summary=tile_corners_summary,
+        manual_parameters=tile_corners_parameters,
     )
     @action(
         detail=False, methods=['get'], url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+)/corners'
@@ -84,6 +89,11 @@ def tile_corners(
 
 
 class TilesDetailMixin(TilesMixin):
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=tile_summary,
+        manual_parameters=tile_parameters,
+    )
     @action(detail=True, url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+).png')
     def tile_png(
         self,
@@ -95,6 +105,11 @@ def tile_png(
     ) -> HttpResponse:
         return super().tile_png(request, x, y, z, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=tile_summary,
+        manual_parameters=tile_parameters,
+    )
     @action(detail=True, url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+).jpeg')
     def tile_jpeg(
         self,
@@ -106,6 +121,11 @@ def tile_jpeg(
     ) -> HttpResponse:
         return super().tile_jpeg(request, x, y, z, pk)
 
+    @swagger_auto_schema(
+        method='GET',
+        operation_summary=tile_corners_summary,
+        manual_parameters=tile_corners_parameters,
+    )
     @action(
         detail=True, methods=['get'], url_path=r'tiles/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+)/corners'
     )