style(api-docs): clean up api documentation.

Previously, it was not possible to check request/response bodies samples in API documentation. This commit solves this error by refactoring the API documentation by using yaml for all api schemas/samples and decomposition of the open-api.yaml file.

- decompose the mod-search.yaml file.
- move all the paths into separate yaml files with corresponded folders inside paths folder.
- move all the parameters into separate yaml files inside the parameters folder.
- create yaml versions for all the examples.
- create yaml versions for all the schemas.
- delete example files with sample extension.
- delete schemas files with json extension.

Closes MSEARCH-546.

.github/workflows/api-lint.yml

@@ -23,7 +23,7 @@ name: api-lint
 env:
   API_TYPES: 'OAS'
   API_DIRECTORIES: 'src/main/resources/swagger.api'
-  API_EXCLUDES: 'paths,responses,schemas'
+  API_EXCLUDES: 'paths responses'
   API_WARNINGS: false
 
 on:

src/main/resources/swagger.api/examples/request/indexRecordRequestBody.yaml

@@ -1,3 +1,4 @@
+example:
 - resourceName: instance
   type: CREATE
   tenant: diku

src/main/resources/swagger.api/examples/request/indexRequestBody.yaml

@@ -1 +1,2 @@
-resourceName: instance
+value:
+  resourceName: instance

src/main/resources/swagger.api/examples/request/streamIdsJobRequest.yaml

@@ -1 +1,3 @@
-query: "title=*"
+value:
+  query: "title=*"
+  entityType: "INSTANCE"

src/main/resources/swagger.api/examples/response/indexRecordResponse.yaml

@@ -1 +1,2 @@
-status: success
+value:
+  status: success

src/main/resources/swagger.api/examples/response/streamIdsJobResponse.yaml

@@ -1,4 +1,6 @@
-id: "eea1432c-beb8-4f4f-b96a-f8de977f1106"
-query: "title=*"
-status: "completed"
-createdDate: "1974-12-03T00:00:00"
+value:
+  id: 'eea1432c-beb8-4f4f-b96a-f8de977f1106'
+  query: 'title=*'
+  status: 'COMPLETED'
+  entityType: 'INSTANCE'
+  createdDate: '1974-12-03T00:00:00'

src/main/resources/swagger.api/mod-search.yaml

@@ -87,6 +87,18 @@ paths:
     $ref: 'paths/browse-config/browse-type-browse-option-id.yaml'
 
 components:
+  schemas:
+    sortOrder:
+      $ref: 'schemas/entity/sortOrder.yaml'
+    browseType:
+      $ref: 'schemas/entity/browseType.yaml'
+    recordType:
+      $ref: 'schemas/entity/recordType.yaml'
+    browseOptionType:
+      $ref: 'schemas/entity/browseOptionType.yaml'
+    callNumberType:
+      $ref: 'schemas/entity/callNumberType.yaml'
+
   responses:
     unprocessableEntityResponse:
       $ref: 'responses/unprocessableEntityResponse.yaml'

src/main/resources/swagger.api/parameters/record-type.yaml

@@ -0,0 +1,5 @@
+name: recordType
+required: true
+in: path
+schema:
+  $ref: '../schemas/entity/recordType.yaml'

src/main/resources/swagger.api/parameters/sort-order-param.yaml

@@ -1,6 +1,6 @@
 in: query
 name: sortOrder
-description: Defines sorting order
+description: 'Defines sorting order'
 required: false
 schema:
   $ref: '../schemas/entity/sortOrder.yaml'

src/main/resources/swagger.api/paths/browse-call-numbers/browse-call-numbers-instances.yaml

@@ -14,8 +14,10 @@ get:
       name: callNumberType
       description: Type of call number
       required: false
-      schema:
-        $ref: '../../schemas/entity/callNumberType.yaml'
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/entity/callNumberType.yaml'
   responses:
     '200':
       description: 'Search result for browsing by call number'

src/main/resources/swagger.api/paths/search-facets/search-record-type-facets.yaml

@@ -4,11 +4,7 @@ get:
   tags:
     - facets
   parameters:
-    - name: recordType
-      required: true
-      in: path
-      schema:
-        $ref: '../../schemas/entity/RecordType.yaml'
+    - $ref: '../../parameters/record-type.yaml'
     - $ref: '../../parameters/cql-query.yaml'
     - $ref: '../../parameters/facet-param.yaml'
     - $ref: '../../parameters/x-okapi-tenant-header.yaml'

src/main/resources/swagger.api/paths/search-index/search-index-indices.yaml

@@ -8,8 +8,9 @@ post:
   requestBody:
     content:
       application/json:
-        example:
-          $ref: '../../examples/request/indexRequestBody.yaml'
+        examples:
+          objectExample:
+            $ref: '../../examples/request/indexRequestBody.yaml'
         schema:
           $ref: '../../schemas/request/createIndexRequest.yaml'
   responses:

src/main/resources/swagger.api/paths/search-index/search-index-records.yaml

@@ -7,16 +7,17 @@ post:
     content:
       application/json:
         example:
-          $ref: '../../examples/request/indexRecordRequestBody.yaml'
+          - $ref: '../../examples/request/indexRecordRequestBody.yaml'
         schema:
           $ref: '../../schemas/request/indexRecordRequest.yaml'
   responses:
     '200':
       description: Response with created indices and status (error message will be present if operation failed)
       content:
         application/json:
-          example:
-            $ref: '../../examples/response/indexRecordResponse.yaml'
+          examples:
+            indexRecordResponse:
+              $ref: '../../examples/response/indexRecordResponse.yaml'
           schema:
             $ref: '../../schemas/response/folioIndexOperationResponse.yaml'
     '500':

src/main/resources/swagger.api/paths/search-resources/search-resources-jobs-job-id.yaml

@@ -11,8 +11,9 @@ get:
       description: 'Job for the stream of resource ids'
       content:
         application/json:
-          example:
-            $ref: '../../examples/response/streamIdsJobResponse.yaml'
+          examples:
+            streamIdsJobResponse:
+              $ref: '../../examples/response/streamIdsJobResponse.yaml'
           schema:
             $ref: '../../schemas/entity/resourceIdsJob.yaml'
     '400':

src/main/resources/swagger.api/paths/search-resources/search-resources-jobs.yaml

@@ -8,17 +8,19 @@ post:
   requestBody:
     content:
       application/json:
-        example:
-          $ref: '../../examples/request/streamIdsJobRequest.yaml'
+        examples:
+          streamIdsJobRequest:
+            $ref: '../../examples/request/streamIdsJobRequest.yaml'
         schema:
           $ref: '../../schemas/entity/resourceIdsJob.yaml'
   responses:
     '200':
       description: 'Job for the stream of resource ids'
       content:
         application/json:
-          example:
-            $ref: '../../examples/response/streamIdsJobResponse.yaml'
+          examples:
+            streamIdsJobResponse:
+              $ref: '../../examples/response/streamIdsJobResponse.yaml'
           schema:
             $ref: '../../schemas/entity/resourceIdsJob.yaml'
     '400':