HTML responses

CHANGES.rst

@@ -12,11 +12,34 @@ Changes
 
 Changes:
 --------
-- No change.
-
-Fixes:
-------
-- No change.
+- Add support of `HTML` responses for `OGC API - Processes` endpoints
+  (fixes `#210 <https://github.com/crim-ca/weaver/issues/210>`_).
+- Add ``weaver.wps_restapi_html`` configuration setting to control support of `HTML` responses.
+- Add ``weaver.wps_restapi_html_override_user_agent`` configuration setting for control of default `HTML` or `JSON`
+  rendering by requests from web browsers.
+- Refactor ``pyramid`` configuration to employ ``Configurator.add_cornice_service``
+  utility instead of ``Configurator.add_route`` and ``Configurator.add_view`` handlers that were causing a lot of
+  duplication between the ``cornice.Service`` parametrization and their corresponding view decorators. All metadata
+  is now embedded within the same decorator operation.
+- Add missing documentation for ``weaver.wps_restapi_doc`` and ``weaver.wps_restapi_ref`` configuration settings.
+- Modified the base path/URL resolution of the `OpenAPI` endpoint to be located at the application root instead of being
+  nested under ``weaver.wps_restapi_path`` or ``weaver.wps_restapi_url``, since the OpenAPI `JSON` and `HTML` responses
+  are employed for representing supported requests and responses of both the `REST` and the `OWS` `WPS` interfaces.
+- Update `Swagger-UI` version for latest rendering fixes of `OpenAPI` definitions.
+- Add automatic redirect from ``/api?f=json`` to ``/json`` response to allow `OpenAPI` schema access directly
+  from the same endpoint as the `Swagger-UI` rendering of the schemas. The ``Accept`` header
+  for ``application/json`` or explicitly ``application/vnd.oai.openapi+json; version=3.0`` are also supported
+  (fixes `#623 <https://github.com/crim-ca/weaver/issues/623>`_)
+- Add `OpenAPI` response rendering as `YAML` using ``/api?f=yaml`` or ``Accept: application/yaml``
+  (relates to `#456 <https://github.com/crim-ca/weaver/issues/456>`_).
+
+Fixes:
+------
+- Fix ``weaver.wps_restapi_path`` incorrectly resolved when populating `Process` paging links.
+- Fix invalid resolution of reported API endpoints in the `OpenAPI` and frontpage response when
+  ``weaver.wps_restapi_path``, ``weaver.wps_restapi_url``, ``weaver.wps_path`` or ``weaver.wps_url``
+  were set to other prefix path values than the default root base URL.
+- Fix ``weaver.formats.OutputFormat`` to return ``JSON`` by default when an invalid format could not be resolved.
 
 .. _changes_5.6.1:
 

config/weaver.ini.example

@@ -147,6 +147,12 @@ weaver.wps_metadata_contact_role=Information
 weaver.wps_restapi = true
 weaver.wps_restapi_url =
 weaver.wps_restapi_path = /
+# Allow OGC API - Processes endpoints to render
+# contents in HTML as alternate responses to JSON.
+weaver.wps_restapi_html = true
+# Special handling of rendering default HTML vs JSON by web browsers.
+# See documentation for details.
+weaver.wps_restapi_html_override_user_agent = false
 
 # --- Weaver job email notification ---
 weaver.wps_email_encrypt_salt = salty-email

docs/source/appendix.rst

@@ -21,6 +21,9 @@ Glossary
     API
         | Application Programming Interface
         | Most typically, referring to the use of HTTP(S) requests following an :term:`OpenAPI` specification.
+        |
+        | In the context of this project, it is also used in some occasion to refer to the RESTful interface
+          of :term:`OGC API - Processes`, in contrast to the :term:`OWS` :term:`WPS` interface.
 
     Application Package
         General term that refers to *"what and how to execute"* the :term:`Process`. Application Packages provide the
@@ -110,9 +113,18 @@ Glossary
         Ontology that regroups multiple definitions, amongst which `Weaver` looks up most of its known and supported
         :term:`MIME-types` (|iana-link|_) when resolving file formats.
 
+    HTML
+        | HyperText Markup Language
+        | Alternative representation of some endpoints provided by the application.
+          Requires appropriate ``Accept`` header or ``f``/``format`` query to return this format.
+
+        .. seealso::
+            See :ref:`OpenAPI Specification` for details.
+
     JSON
         | JavaScript Object Notation
-        | Default data representation of all objects contained in the application or for their creation.
+        | Default data representation of all objects contained in the application or for their creation
+          when using the :term:`API`, except for the :term:`OWS` :term:`WPS` endpoint.
 
     Job
         Definition of a :term:`Process` execution state with applicable operation metadata.
@@ -262,8 +274,12 @@ Glossary
 
     XML
         | Extensible Markup Language
-        | Alternative representation of some data object provided by the application. Requires appropriate ``Accept``
-          header to return this format. See :ref:`OpenAPI Specification` for details.
+        | Alternative representation of some data object provided by the application.
+          Requires appropriate ``Accept`` header or ``f``/``format`` query to return this format.
+          For the :term:`OWS` :term:`WPS` endpoint, this is the default representation instead of :term:`JSON`.
+
+        .. seealso::
+            See :ref:`OpenAPI Specification` for details.
 
     YAML
         | YAML Ain't Markup Language

docs/source/conf.py

@@ -97,9 +97,16 @@ def doc_redirect_include(file_path):
 #   configuration for the purpose of parsing the source to generate the OpenAPI
 config = Configurator(settings={"weaver.wps": True, "weaver.wps_restapi": True, "weaver.build_docs": True})
 config.include("weaver")  # need to include package to apply decorators and parse routes
+config.commit()
 api_spec_file = os.path.join(DOC_BLD_ROOT, "api.json")
 # must disable references when using redoc (alpha version note rendering them correctly)
-api_spec_json = get_openapi_json(http_host="example", http_scheme="https", use_docstring_summary=True, use_refs=False)
+api_spec_json = get_openapi_json(
+    http_host="example",
+    http_scheme="https",
+    use_docstring_summary=True,
+    use_refs=False,
+    container=config,
+)
 if not os.path.isdir(DOC_BLD_ROOT):
     os.makedirs(DOC_BLD_ROOT)
 with open(api_spec_file, "w") as f: