Added examples in the Open API definition of the admin API routes

pygeoapi-config.yml

@@ -53,10 +53,12 @@ server:
 #        connection: /tmp/pygeoapi-process-manager.db
 #        output_dir: /tmp/
     # ogc_schemas_location: /opt/schemas.opengis.net
-
+    admin: false # enable admin API
+
 logging:
     level: ERROR
     #logfile: /tmp/pygeoapi.log
+
 
 metadata:
     identification:

pygeoapi/openapi.py

@@ -7,6 +7,7 @@
 # Copyright (c) 2024 Tom Kralidis
 # Copyright (c) 2022 Francesco Bartoli
 # Copyright (c) 2023 Ricardo Garcia Silva
+# Copyright (c) 2024 Joana Simoes
 #
 # Permission is hereby granted, free of charge, to any person
 # obtaining a copy of this software and associated documentation
@@ -38,7 +39,7 @@
 import os
 from pathlib import Path
 from typing import Union
-
+import random
 import click
 from jsonschema import validate as jsonschema_validate
 import yaml
@@ -509,7 +510,7 @@ def get_oas_30(cfg: dict, fail_on_invalid_collection: bool = True) -> dict:
         schema_dict = get_config_schema()
         oas['definitions'] = schema_dict['definitions']
         LOGGER.debug('Adding admin endpoints')
-        oas['paths'].update(get_admin())
+        oas['paths'].update(get_admin(cfg))
 
     return oas
 
@@ -641,7 +642,8 @@ def get_oas_30_parameters(cfg: dict, locale_: str):
                 'description': 'Configuration resource identifier',
                 'required': True,
                 'schema': {
-                    'type': 'string'
+                    'type': 'string',
+                    'default': 'obs'
                  }
             }
         }
@@ -666,7 +668,156 @@ def get_config_schema():
         return yaml_load(fh2)
 
 
-def get_admin():
+def remove_timestamps(cfg: dict) -> dict:
+    """
+    Removes timestamps from sample configuration, as they are being
+    translated to strings
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    for key in cfg['resources'].keys():
+        extents = cfg['resources'][key].get('extents')
+        if (extents is not None and 'temporal' in extents.keys()):
+            del extents['temporal']
+
+    return cfg
+
+
+def get_put_config(cfg: dict) -> dict:
+    """
+    Creates the payload for the PUT admin config request
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    put = deepcopy(cfg)
+
+    put['metadata']['identification']['title']['en'] = 'New pygeoapi Title'
+    put['metadata']['identification']['title']['fr'] = 'Nouveau pygeoapi Titre'
+
+    # If there are resources with timestamps, we have to remove the
+    # timestamps from the configuration.
+    if 'resources' in put.keys():
+        remove_timestamps(put)
+
+    return put
+
+
+def get_patch_config(cfg: dict) -> dict:
+    """
+    Creates the payload for the PATCH admin config request
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    patch = deepcopy(cfg)
+
+    patch['metadata']['identification']['title']['en'] = 'Patched pygeoapi'
+    patch['resources'] = {}
+
+    return patch
+
+
+def gen_collection_name():
+    """
+    Generates a collection name, based on a list.
+    Inspired by moby/docker:
+    https://github.com/moby/moby/blob/master/pkg/namesgenerator/names-generator.go
+
+    :returns: collection name
+    """
+
+    names = ['agnesi', 'allen', 'almeida', 'antonelli',
+             'austin', 'borg', 'clark']
+
+    return random.choice(names)
+
+
+def get_post_resource(cfg: dict) -> dict:
+    """
+    Creates the payload for the POST resource admin request
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    collection = gen_collection_name()
+
+    if (len(cfg['resources']) < 1 or 'obs' not in cfg['resources'].keys()):
+        return ''
+
+    post = {collection: {}}
+    post[collection] = deepcopy(cfg['resources']['obs'])
+
+    if 'temporal' in post[collection]['extents'].keys():
+        del post[collection]['extents']['temporal']
+
+    post[collection]['title'] = 'More observations'
+    post[collection]['description'] = 'More cool observations'
+
+    return post
+
+
+def get_put_resource(cfg: dict) -> dict:
+    """
+    Creates the payload for the PUT resource admin request
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    if (len(cfg['resources']) < 1 or 'obs' not in cfg['resources'].keys()):
+        return ''
+
+    put = deepcopy(cfg['resources']['obs'])
+
+    if 'temporal' in put['extents'].keys():
+        del put['extents']['temporal']
+
+    put['title'] = 'New observations'
+    put['description'] = 'New observations description'
+
+    return put
+
+
+def get_patch_resource(cfg: dict) -> dict:
+    """
+    Creates the payload for the PATCH resource admin request
+
+    :param cfg: `dict` of configuration
+
+    :returns: dict of OpenAPI definition
+    """
+
+    if (len(cfg['resources']) < 1 or 'obs' not in cfg['resources'].keys()):
+        return ''
+
+    patch = deepcopy(cfg['resources']['obs'])
+
+    if 'temporal' in patch['extents'].keys():
+        del patch['extents']['temporal']
+
+    patch['title'] = 'Patched collection title'
+    del patch['providers']
+
+    return patch
+
+
+def get_admin(cfg: dict) -> dict:
+    """
+    Generates an OpenAPI definition for the admin API
+
+    :param cfg: `dict` of configuration
+    """
 
     schema_dict = get_config_schema()
 
@@ -702,6 +853,7 @@ def get_admin():
                 'description': 'Updates admin configuration',
                 'content': {
                     'application/json': {
+                        'example': get_put_config(cfg),
                         'schema': schema_dict
                     }
                 },
@@ -722,6 +874,7 @@ def get_admin():
                 'description': 'Updates admin configuration',
                 'content': {
                     'application/json': {
+                        'example': get_patch_config(cfg),
                         'schema': schema_dict
                     }
                 },
@@ -764,6 +917,7 @@ def get_admin():
                 'description': 'Adds resource to configuration',
                 'content': {
                     'application/json': {
+                        'example': get_post_resource(cfg),
                         'schema': schema_dict['properties']['resources']['patternProperties']['^.*$']  # noqa
                     }
                 },
@@ -810,6 +964,7 @@ def get_admin():
                 'description': 'Updates admin configuration resource',
                 'content': {
                     'application/json': {
+                        'example': get_put_resource(cfg),
                         'schema': schema_dict['properties']['resources']['patternProperties']['^.*$']  # noqa
                     }
                 },
@@ -833,6 +988,7 @@ def get_admin():
                 'description': 'Updates admin configuration resource',
                 'content': {
                     'application/json': {
+                        'example': get_patch_resource(cfg),
                         'schema': schema_dict['properties']['resources']['patternProperties']['^.*$']  # noqa
                     }
                 },