feat: enhance CKAN and Discovery API

- add retrieve dataset/package endpoint
- add tag to endpoints
- add error reponse
- reduce reponse attributes to minimise data usage
- improve API description

_http/ckan.http

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2024 PNED G.I.E.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+GET https://ckan-test.healthdata.nl/api/3/action/package_search?facet.field=["organization","theme","conforms_to","has_version","access_rights","language","publisher_name","res_format","provenance"]&rows=1&fq=id:e1b3eff9-13eb-48b0-b180-7ecb76b84454
+
+###
+GET https://ckan-test.healthdata.nl/api/3/action/package_show?id=e1b3eff9-13eb-48b0-b180-7ecb76b84454

src/main/openapi/ckan.yaml

@@ -8,12 +8,14 @@ info:
   version: 1.0.0
   description: API for searching CKAN packages using various criteria.
 servers:
-  - url: http://example.com/api/3/action
+  - url: /
 paths:
-  /package_search:
+  /api/3/action/package_search:
     get:
       summary: Searches for packages based on criteria
-      operationId: packageSearch
+      operationId: package_search
+      tags:
+        - "ckan-query"
       parameters:
         - name: q
           in: query
@@ -28,16 +30,6 @@ paths:
           required: false
           schema:
             type: string
-        - name: fq_list
-          in: query
-          description: Additional filter queries
-          required: false
-          style: form
-          explode: true
-          schema:
-            type: array
-            items:
-              type: string
         - name: sort
           in: query
           description: Sorting of search results
@@ -52,132 +44,158 @@ paths:
           schema:
             type: integer
             default: 10
+            minimum: 0
             maximum: 1000
         - name: start
           in: query
           description: Offset in the complete result set
           required: false
           schema:
             type: integer
-        - name: facet
+            default: 0
+            minimum: 0
+        - name: facet.field
           in: query
-          description: Whether to enable faceted results
+          description: Which facets to include in the response
           required: false
           schema:
             type: string
-            default: "true"
       responses:
-        '200':
+        "200":
           description: A list of packages matching the search criteria
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  count:
-                    type: integer
-                    description: The number of results found
-                  results:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Dataset'
-                  search_facets:
-                    type: object
-                    additionalProperties: true
-                    description: Aggregated information about facet counts
+                $ref: "#/components/schemas/PackagesSearchResponse"
+  /api/3/action/package_show:
+    get:
+      summary: Retrieves a package by ID
+      operationId: package_show
+      tags:
+        - "ckan-query"
+      parameters:
+        - name: id
+          in: query
+          description: The ID of the package to retrieve
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The package with the specified ID
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CkanPackage"
 components:
   schemas:
-    Dataset:
+    PackagesSearchResponse:
+      type: object
+      properties:
+        count:
+          type: integer
+          description: The number of results found
+        results:
+          type: array
+          items:
+            $ref: "#/components/schemas/CkanPackage"
+        facets:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CkanFacetCounts"
+          description: Aggregated information about facet counts
+    CkanFacetCounts:
+      type: object
+      additionalProperties:
+        type: integer
+    CkanPackage:
       type: object
       properties:
         id:
           type: string
-        title:
-          type: string
-        source:
-          type: string
-        version:
-          type: string
-        author:
-          type: string
-        authorEmail:
-          type: string
-        maintainer:
-          type: string
-        maintainerEmail:
-          type: string
-        contactURI:
-          type: string
-        contactName:
-          type: string
-        contactEmail:
-          type: string
-        publisher:
-          type: string
-        publisherName:
-          type: string
-        publisherEmail:
-          type: string
-        publisherURL:
-          type: string
-        publisherType:
-          type: string
-        spatialURI:
+        identifier:
           type: string
-        temporalStartDate:
+        name:
           type: string
-        temporalEndDate:
+        notes:
           type: string
         theme:
+          type: array
+          items:
+            type: string
+        publisher_name:
           type: string
-        versionNotes:
-          type: string
-        landingPage:
-          type: string
-        spatialResolutionInMeters:
-          type: string
-        temporalResolution:
-          type: string
-        qualifiedRelation:
-          type: string
-        accessRights:
-          type: string
-        frequency:
-          type: string
-        conformsTo:
+        organization:
+          $ref: "#/components/schemas/CkanOrganization"
+        metadata_created:
           type: string
-        creator:
+          format: date-time
+        metadata_modified:
           type: string
-        isReferencedBy:
+          format: date-time
+        url:
           type: string
-        isVersionOf:
+        language:
+          type: array
+          items:
+            type: string
+        contact_uri: #TODO check if there are other attributes to form value/label
           type: string
-        identifier:
+        has_version:
+          type: array
+          items:
+            type: string
+        access_rights:
           type: string
-        issued:
+        conforms_to:
+          type: array
+          items:
+            type: string
+        provenance:
           type: string
-        language:
+        spatial_uri: #TODO check if there are other attributes to form value/label
           type: string
-        modificationDate:
+        resources:
+          type: array
+          items:
+            $ref: "#/components/schemas/CkanResource"
+      required:
+        - id
+        - title
+    CkanOrganization:
+      type: object
+      properties:
+        id:
           type: string
-        provenance:
+        name:
           type: string
-        relation:
+        title:
           type: string
-        sample:
+      required:
+        - id
+        - name
+        - title
+    CkanResource:
+      type: object
+      properties:
+        id:
           type: string
-        type:
+        name:
           type: string
-        hasVersion:
+        description:
           type: string
-        documentation:
+        format:
           type: string
-        qualifiedAttribution:
+        uri:
           type: string
-        wasGeneratedBy:
+        created:
           type: string
-        alternateIdentifier:
+          format: date-time
+        last_modified:
           type: string
+          format: date-time
       required:
         - id
-        - title
+        - name
+        - description
+        - created