Merge pull request #5324 from entur/otp2_gbfs_geofencing

Enable GBFS geofencing with VehicleRentalServiceDirectory

doc-templates/sandbox/VehicleRentalServiceDirectory.md

@@ -0,0 +1,39 @@
+# Vehicle Rental Service Directory API support.
+
+This adds support for the GBFS service directory endpoint component located at 
+https://github.com/entur/lamassu. OTP uses the service directory to lookup and connect to all GBFS
+endpoints registered in the directory. This simplifies the management of the GBFS endpoints, since
+multiple services/components like OTP can connect to the directory and get the necessary
+configuration from it.
+
+
+## Contact Info
+
+- Entur, Norway
+
+
+## Changelog
+
+- Initial implementation of bike share updater API support
+- Make json tag names configurable [#3447](https://github.com/opentripplanner/OpenTripPlanner/pull/3447)
+- Enable GBFS geofencing with VehicleRentalServiceDirectory [#5324](https://github.com/opentripplanner/OpenTripPlanner/pull/5324)
+
+
+## Configuration
+
+To enable this you need to specify a url for the `vehicleRentalServiceDirectory` in
+the `router-config.json`
+
+### Parameter Summary
+
+<!-- INSERT: PARAMETERS-TABLE -->
+
+
+### Parameter Details
+
+<!-- INSERT: PARAMETERS-DETAILS -->
+
+
+### Example
+
+<!-- INSERT: JSON-EXAMPLE -->

docs/RouterConfiguration.md

@@ -67,13 +67,7 @@ A full list of them can be found in the [RouteRequest](RouteRequest.md).
 |    [tracingHeaderTags](#transmodelApi_tracingHeaderTags)                                  |       `string[]`      | Used to group requests when monitoring OTP.                                                           | *Optional* |               |   na  |
 | [updaters](UpdaterConfig.md)                                                              |       `object[]`      | Configuration for the updaters that import various types of data into OTP.                            | *Optional* |               |  1.5  |
 | [vectorTileLayers](sandbox/MapboxVectorTilesApi.md)                                       |       `object[]`      | Configuration of the individual layers for the Mapbox vector tiles.                                   | *Optional* |               |  2.0  |
-| vehicleRentalServiceDirectory                                                             |        `object`       | Configuration for the vehicle rental service directory.                                               | *Optional* |               |  2.0  |
-|    language                                                                               |        `string`       | Language code.                                                                                        | *Optional* |               |   na  |
-|    sourcesName                                                                            |        `string`       | Json tag name for updater sources.                                                                    | *Optional* | `"systems"`   |   na  |
-|    updaterNetworkName                                                                     |        `string`       | Json tag name for the network name for each source.                                                   | *Optional* | `"id"`        |   na  |
-|    updaterUrlName                                                                         |        `string`       | Json tag name for endpoint urls for each source.                                                      | *Optional* | `"url"`       |   na  |
-|    url                                                                                    |         `uri`         | Endpoint for the VehicleRentalServiceDirectory                                                        | *Required* |               |   na  |
-|    [headers](#vehicleRentalServiceDirectory_headers)                                      |    `map of string`    | HTTP headers to add to the request. Any header key, value can be inserted.                            | *Optional* |               |   na  |
+| [vehicleRentalServiceDirectory](sandbox/VehicleRentalServiceDirectory.md)                 |        `object`       | Configuration for the vehicle rental service directory.                                               | *Optional* |               |  2.0  |
 
 <!-- PARAMETERS-TABLE END -->
 
@@ -415,13 +409,6 @@ Only turn this feature on if you have unique ids across all feeds, without the f
 
 Used to group requests when monitoring OTP.
 
-<h3 id="vehicleRentalServiceDirectory_headers">headers</h3>
-
-**Since version:** `na` ∙ **Type:** `map of string` ∙ **Cardinality:** `Optional`   
-**Path:** /vehicleRentalServiceDirectory 
-
-HTTP headers to add to the request. Any header key, value can be inserted.
-
 
 <!-- PARAMETERS-DETAILS END -->
 

docs/sandbox/VehicleRentalServiceDirectory.md

@@ -1,24 +1,102 @@
 # Vehicle Rental Service Directory API support.
 
+This adds support for the GBFS service directory endpoint component located at 
+https://github.com/entur/lamassu. OTP uses the service directory to lookup and connect to all GBFS
+endpoints registered in the directory. This simplifies the management of the GBFS endpoints, since
+multiple services/components like OTP can connect to the directory and get the necessary
+configuration from it.
+
+
 ## Contact Info
 
-- Gard Mellemstrand, Entur, Norway
+- Entur, Norway
+
 
 ## Changelog
 
 - Initial implementation of bike share updater API support
-- Make json tag names
-  configurable [#3447](https://github.com/opentripplanner/OpenTripPlanner/pull/3447)
-
-## Documentation
+- Make json tag names configurable [#3447](https://github.com/opentripplanner/OpenTripPlanner/pull/3447)
+- Enable GBFS geofencing with VehicleRentalServiceDirectory [#5324](https://github.com/opentripplanner/OpenTripPlanner/pull/5324)
 
-This adds support for the GBFS service directory endpoint component located
-at https://github.com/entur/lahmu. OTP use the service directory to lookup and connect to all GBFS
-endpoints registered in the directory. This simplify the management of the GBFS endpoints, since
-multiple services/components like OTP can connect to the directory and get the necessary
-configuration from it.
 
-### Configuration
+## Configuration
 
 To enable this you need to specify a url for the `vehicleRentalServiceDirectory` in
 the `router-config.json`
+
+### Parameter Summary
+
+<!-- PARAMETERS-TABLE BEGIN -->
+<!-- NOTE! This section is auto-generated. Do not change, change doc in code instead. -->
+
+| Config Parameter                                    |       Type      | Summary                                                                         |  Req./Opt. | Default Value | Since |
+|-----------------------------------------------------|:---------------:|---------------------------------------------------------------------------------|:----------:|---------------|:-----:|
+| language                                            |     `string`    | Language code.                                                                  | *Optional* |               |  2.1  |
+| sourcesName                                         |     `string`    | Json tag name for updater sources.                                              | *Optional* | `"systems"`   |  2.1  |
+| updaterNetworkName                                  |     `string`    | Json tag name for the network name for each source.                             | *Optional* | `"id"`        |  2.1  |
+| updaterUrlName                                      |     `string`    | Json tag name for endpoint urls for each source.                                | *Optional* | `"url"`       |  2.1  |
+| url                                                 |      `uri`      | Endpoint for the VehicleRentalServiceDirectory                                  | *Required* |               |  2.1  |
+| [headers](#vehicleRentalServiceDirectory_headers)   | `map of string` | HTTP headers to add to the request. Any header key, value can be inserted.      | *Optional* |               |  2.1  |
+| [networks](#vehicleRentalServiceDirectory_networks) |    `object[]`   | List all networks to include. Use "network": "default-network" to set defaults. | *Optional* |               |  2.4  |
+|       geofencingZones                               |    `boolean`    | Enables geofencingZones for the given network                                   | *Optional* | `false`       |  2.4  |
+|       network                                       |     `string`    | The network name                                                                | *Required* |               |  2.4  |
+
+<!-- PARAMETERS-TABLE END -->
+
+
+### Parameter Details
+
+<!-- PARAMETERS-DETAILS BEGIN -->
+<!-- NOTE! This section is auto-generated. Do not change, change doc in code instead. -->
+
+<h4 id="vehicleRentalServiceDirectory_headers">headers</h4>
+
+**Since version:** `2.1` ∙ **Type:** `map of string` ∙ **Cardinality:** `Optional`   
+**Path:** /vehicleRentalServiceDirectory 
+
+HTTP headers to add to the request. Any header key, value can be inserted.
+
+<h4 id="vehicleRentalServiceDirectory_networks">networks</h4>
+
+**Since version:** `2.4` ∙ **Type:** `object[]` ∙ **Cardinality:** `Optional`   
+**Path:** /vehicleRentalServiceDirectory 
+
+List all networks to include. Use "network": "default-network" to set defaults.
+
+If no default network exists only the listed networks are used. Configure a network with
+name "default-network" to include all unlisted networks. If not present, all unlisted
+networks are dropped. Note! The values in the "default-network" are not used to set
+missing field values in networks listed.
+
+
+
+<!-- PARAMETERS-DETAILS END -->
+
+
+### Example
+
+<!-- JSON-EXAMPLE BEGIN -->
+<!-- NOTE! This section is auto-generated. Do not change, change doc in code instead. -->
+
+```JSON
+// router-config.json
+{
+  "vehicleRentalServiceDirectory" : {
+    "url" : "https://example.com",
+    "sourcesName" : "systems",
+    "updaterUrlName" : "url",
+    "updaterNetworkName" : "id",
+    "headers" : {
+      "ET-Client-Name" : "otp"
+    },
+    "networks" : [
+      {
+        "network" : "oslo-by-sykkel",
+        "geofencingZones" : true
+      }
+    ]
+  }
+}
+```
+
+<!-- JSON-EXAMPLE END -->

src/ext-test/java/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/VehicleRentalServiceDirectoryConfigDocTest.java

@@ -0,0 +1,68 @@
+package org.opentripplanner.ext.vehiclerentalservicedirectory.generatedoc;
+
+import static org.opentripplanner.framework.application.OtpFileNames.ROUTER_CONFIG_FILENAME;
+import static org.opentripplanner.framework.io.FileUtils.assertFileEquals;
+import static org.opentripplanner.framework.io.FileUtils.readFile;
+import static org.opentripplanner.framework.io.FileUtils.writeFile;
+import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4;
+import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT;
+import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT;
+import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceJsonExample;
+import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersDetails;
+import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersTable;
+import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource;
+
+import java.io.File;
+import org.junit.jupiter.api.Test;
+import org.opentripplanner.generate.doc.framework.GeneratesDocumentation;
+import org.opentripplanner.generate.doc.framework.ParameterDetailsList;
+import org.opentripplanner.generate.doc.framework.ParameterSummaryTable;
+import org.opentripplanner.generate.doc.framework.SkipNodes;
+import org.opentripplanner.generate.doc.framework.TemplateUtil;
+import org.opentripplanner.standalone.config.RouterConfig;
+import org.opentripplanner.standalone.config.framework.json.NodeAdapter;
+
+@GeneratesDocumentation
+public class VehicleRentalServiceDirectoryConfigDocTest {
+
+  private static final String DOCUMENT = "sandbox/VehicleRentalServiceDirectory.md";
+  private static final File TEMPLATE = new File(TEMPLATE_ROOT, DOCUMENT);
+  private static final File OUT_FILE = new File(DOCS_ROOT, DOCUMENT);
+  private static final String CONFIG_PATH =
+    "org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/" + ROUTER_CONFIG_FILENAME;
+  private static final String CONFIG_TAG = "vehicleRentalServiceDirectory";
+  private static final SkipNodes SKIP_NODES = SkipNodes.of().build();
+
+  @Test
+  public void updateConfigurationDoc() {
+    NodeAdapter node = readConfigDefaults();
+
+    // Read and close inout file (same as output file)
+    String doc = readFile(TEMPLATE);
+    String original = readFile(OUT_FILE);
+
+    doc = replaceParametersTable(doc, getParameterSummaryTable(node));
+    doc = replaceParametersDetails(doc, getParameterDetailsList(node));
+
+    var example = TemplateUtil.jsonExampleBuilder(node.rawNode()).wrapInObject(CONFIG_TAG).build();
+    doc = replaceJsonExample(doc, example, ROUTER_CONFIG_FILENAME);
+
+    writeFile(OUT_FILE, doc);
+
+    assertFileEquals(original, OUT_FILE);
+  }
+
+  private NodeAdapter readConfigDefaults() {
+    var json = jsonNodeFromResource(CONFIG_PATH);
+    var conf = new RouterConfig(json, CONFIG_PATH, false);
+    return conf.asNodeAdapter().child(CONFIG_TAG);
+  }
+
+  private String getParameterSummaryTable(NodeAdapter node) {
+    return new ParameterSummaryTable(SKIP_NODES).createTable(node).toMarkdownTable();
+  }
+
+  private String getParameterDetailsList(NodeAdapter node) {
+    return ParameterDetailsList.listParametersWithDetails(node, SKIP_NODES, HEADER_4);
+  }
+}

src/ext-test/resources/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/router-config.json

@@ -0,0 +1,17 @@
+{
+  "vehicleRentalServiceDirectory": {
+    "url": "https://example.com",
+    "sourcesName": "systems",
+    "updaterUrlName": "url",
+    "updaterNetworkName": "id",
+    "headers": {
+      "ET-Client-Name": "otp"
+    },
+    "networks": [
+      {
+        "network" : "oslo-by-sykkel",
+        "geofencingZones" : true
+      }
+    ]
+  }
+}