Add search query parameters in OpenAPI

arkindex/documents/api/iiif.py

@@ -4,6 +4,7 @@ from rest_framework.generics import RetrieveAPIView
 from rest_framework.exceptions import PermissionDenied
 from arkindex_common.enums import TranscriptionType
 from arkindex.documents.models import Element, ElementType, Corpus
+from arkindex.documents.serializers.search import IIIFSearchQuerySerializer
 from arkindex.documents.serializers.iiif import \
     VolumeManifestSerializer, ActManifestSerializer, \
     PageAnnotationListSerializer, PageActAnnotationListSerializer, \
@@ -108,6 +109,7 @@ class TranscriptionSearchAnnotationList(SearchAPIMixin, RetrieveAPIView):
     """
 
     serializer_class = TranscriptionSearchAnnotationListSerializer
+    query_serializer_class = IIIFSearchQuerySerializer
     elt = None
 
     def get_element(self):

arkindex/documents/api/search.py

@@ -83,6 +83,12 @@ class EntitySearch(SearchAPIView):
     """
     serializer_class = EntitySearchResultSerializer
     query_serializer_class = EntitySearchQuerySerializer
+    openapi_overrides = {
+        'description': 'Get a list of entities',
+        'operationId': 'SearchEntities',
+        'security': [],
+        'tags': ['search'],
+    }
 
     def get_search(self, query=None, type=None, corpora_ids=None):
         assert corpora_ids, 'Must filter by corpora'

arkindex/documents/serializers/search.py

@@ -65,6 +65,14 @@ class EntitySearchQuerySerializer(serializers.Serializer):
     corpus = serializers.UUIDField(source='corpus_id', default=None)
 
 
+class IIIFSearchQuerySerializer(serializers.Serializer):
+    """
+    Search parameters for IIIF transcription search
+    See https://iiif.io/api/search/1.0/#request-1
+    """
+    q = serializers.CharField(source='query', default=None)
+
+
 class ElementSearchResultSerializer(serializers.ModelSerializer):
     """
     A page search result with nested transcriptions

arkindex/project/mixins.py

@@ -3,6 +3,7 @@ from rest_framework.exceptions import PermissionDenied
 from arkindex.documents.models import Corpus, Right
 from arkindex.documents.serializers.search import SearchQuerySerializer
 from arkindex.project.elastic import ESQuerySet
+from arkindex.project.openapi import SearchAutoSchema
 
 
 class CorpusACLMixin(object):
@@ -39,6 +40,7 @@ class NestedCorpusMixin(CorpusACLMixin):
 
 class SearchAPIMixin(CorpusACLMixin):
     query_serializer_class = SearchQuerySerializer
+    schema = SearchAutoSchema()
     search = None
 
     def get_search(self, **query):
@@ -52,7 +54,7 @@ class SearchAPIMixin(CorpusACLMixin):
         serializer.is_valid(raise_exception=True)
         query = serializer.validated_data
         # TODO Handle corpus field in serializer too
-        if query['corpus_id']:
+        if query.get('corpus_id'):
             try:
                 query['corpora_ids'] = [str(self.get_corpus(query['corpus_id']).id), ]
             except Corpus.DoesNotExist:
@@ -63,7 +65,7 @@ class SearchAPIMixin(CorpusACLMixin):
                 Corpus.objects.readable(self.request.user).values_list('id', flat=True),
             ))
 
-        del query['corpus_id']
+        query.pop('corpus_id', None)
         search = self.get_search(**query)
         return ESQuerySet(self.post_process, search)
 

arkindex/project/openapi.py

@@ -89,3 +89,28 @@ class AutoSchema(BaseAutoSchema):
             operation.update(self.view.openapi_overrides)
 
         return operation
+
+
+class SearchAutoSchema(AutoSchema):
+    """
+    A special schema generators that parses a search query serializer into query string params,
+    to allow API clients to perform searches.
+    """
+
+    def _get_filter_parameters(self, path, method):
+        parameters = super()._get_filter_parameters(path, method)
+        serializer_class = getattr(self.view, 'query_serializer_class', None)
+        if not serializer_class:
+            return parameters
+        serializer = serializer_class()
+        serializer_schema = self._map_serializer(serializer)
+        return parameters + [
+            {
+                'name': field_name,
+                'in': 'query',
+                'required': field_name in serializer_schema.get('required', []),
+                'description': '',
+                'schema': field_schema,
+            }
+            for field_name, field_schema in serializer_schema['properties'].items()
+        ]

openapi/patch.yml

@@ -392,12 +392,6 @@ paths:
       description: Update an entity
       tags:
       - entities
-  /api/v1/entity/search/:
-    get:
-      description: Get a list of entities
-      operationId: SearchEntities
-      tags:
-        - search
   /api/v1/entity/{id}/elements/:
     get:
       operationId: ListEntityElements