NUTCH-2931 Create OpenAPI specification for Nutch 1.x REST API

.github/workflows/master-build.yml

@@ -85,6 +85,29 @@ jobs:
         if: ${{ env.UNKNOWN_LICENSES != '0 Unknown Licenses' }}
         run: exit 1
 
+  openapi-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36
+        id: filter
+        with:
+          filters: |
+            openapi:
+              - 'openapi.yaml'
+              - '.spectral.yaml'
+      - name: Set up Node.js
+        if: steps.filter.outputs.openapi == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      - name: Install IBM OpenAPI Validator
+        if: steps.filter.outputs.openapi == 'true'
+        run: npm install --no-save ibm-openapi-validator
+      - name: Validate OpenAPI specification
+        if: steps.filter.outputs.openapi == 'true'
+        run: ./node_modules/.bin/lint-openapi openapi.yaml
+
   # Build verification with Java bytecode target matrix
   # Verifies bytecode compatibility for both Java 11 and Java 17 targets
   build:

.spectral.yaml

@@ -0,0 +1,29 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Custom Spectral ruleset for the Apache Nutch REST API.
+# Extends the IBM Cloud Validation Ruleset and disables rules that conflict
+# with the existing Nutch Java wire format (camelCase properties, UPPER_CASE
+# enums, camelCase parameters, bare-array responses, map-typed responses,
+# and consecutive path parameter segments).
+
+extends: "@ibm-cloud/openapi-ruleset"
+rules:
+  ibm-property-casing-convention: off
+  ibm-enum-casing-convention: off
+  ibm-parameter-casing-convention: off
+  ibm-no-array-responses: off
+  ibm-accept-and-return-models: off
+  ibm-no-consecutive-path-parameter-segments: off

docker/Dockerfile

@@ -18,8 +18,8 @@
 
 # BUILD_MODE can be either
 #  0 == Nutch master branch source install with 'crawl' and 'nutch' scripts on PATH
-#  1 == Same as mode 0 with addition of Nutch REST Server
-#  2 == Same as mode 1 with addition of Nutch WebApp
+#  1 == (DEPRECATED) Same as mode 0 with addition of Nutch REST Server
+#  2 == (DEPRECATED) Same as mode 1 with addition of Nutch WebApp
 ARG BUILD_MODE=0
 
 FROM alpine:3.19 AS base
@@ -67,6 +67,7 @@ RUN echo "Nutch master branch source install with 'crawl' and 'nutch' scripts on
 
 FROM base AS branch-version-1
 
+RUN echo "WARNING: BUILD_MODE=1 (server) is deprecated and will be removed in a future version of Nutch. The Nutch REST server is superseded by the OpenAPI specification (openapi.yaml)."
 RUN echo "Nutch master branch source install with 'crawl' and 'nutch' scripts on PATH and Nutch REST Server on $SERVER_HOST:$SERVER_PORT"
 ARG SERVER_PORT=8081
 ARG SERVER_HOST=0.0.0.0
@@ -86,6 +87,7 @@ ENTRYPOINT [ "supervisord", "--nodaemon", "--configuration", "/etc/supervisord.c
 
 FROM base AS branch-version-2
 
+RUN echo "WARNING: BUILD_MODE=2 (server + webapp) is deprecated and will be removed in a future version of Nutch. The Nutch REST server and webapp are superseded by the OpenAPI specification (openapi.yaml)."
 RUN echo "Nutch master branch source install with 'crawl' and 'nutch' scripts on PATH, Nutch REST Server on $SERVER_HOST:$SERVER_PORT and WebApp on this container port $WEBAPP_PORT"
 ARG SERVER_PORT=8081
 ARG SERVER_HOST=0.0.0.0

ivy/ivy.xml

@@ -90,15 +90,20 @@
 			<exclude module="hadoop-client" />
 		</dependency>
 
+		<!-- Deprecated: The following dependencies are used exclusively by the Nutch REST
+		     service (org.apache.nutch.service) and will be removed along with
+		     the service in a future version of Nutch. -->
 		<dependency org="org.apache.cxf" name="cxf-rt-frontend-jaxws" rev="3.6.9" conf="*->default" />
 		<dependency org="org.apache.cxf" name="cxf-rt-frontend-jaxrs" rev="3.6.9" conf="*->default" />
 		<dependency org="org.apache.cxf" name="cxf-rt-transports-http" rev="3.6.9" conf="*->default" />
 		<dependency org="org.apache.cxf" name="cxf-rt-transports-http-jetty" rev="3.6.9" conf="*->default" />
 		<dependency org="org.apache.cxf" name="cxf-rt-rs-client" rev="3.6.9" conf="test->default" />
+		<dependency org="com.fasterxml.jackson.jaxrs" name="jackson-jaxrs-json-provider" rev="2.18.5" conf="*->default" />
+		<!-- Deprecated: End service deprecations -->
+
 		<dependency org="com.fasterxml.jackson.core" name="jackson-databind" rev="2.18.5" conf="*->default" />
 		<dependency org="com.fasterxml.jackson.core" name="jackson-annotations" rev="2.18.5" conf="*->default" />
 		<dependency org="com.fasterxml.jackson.dataformat" name="jackson-dataformat-cbor" rev="2.18.5" conf="*->default" />
-		<dependency org="com.fasterxml.jackson.jaxrs" name="jackson-jaxrs-json-provider" rev="2.18.5" conf="*->default" />
 
 		<!-- WARC artifacts needed -->
 		<dependency org="org.netpreserve.commons" name="webarchive-commons" rev="3.0.2" conf="*->default">