docs: describe GeoJSON fields in directions response

[merydian]

Pull Request Checklist

• 1. I have rebased the latest version of the main branch into my feature branch and all conflicts
  have been resolved.
• 2. I have added information about the change/addition to functionality to the CHANGELOG.md file under the
  [Unreleased] heading.
• 3. I have documented my code using JDocs tags.
• 4. I have removed unnecessary commented out code, imports and System.out.println statements.
• 5. I have written JUnit tests for any new methods/classes and ensured that they pass.
• 6. I have created API tests for any new functionality exposed to the API.
• 7. If changes/additions are made to the ors-config.json file, I have added these to the ors config documentation
  along with a short description of what it is for, and documented this in the Pull Request (below).
• 8. I have built graphs with my code of the Heidelberg.osm.gz file and run the api-tests with all test passing
• 9. I have referenced the Issue Number in the Pull Request (if the changes were from an issue).
• 10. For new features or changes involving building of graphs, I have tested on a larger dataset
  (at least Germany), and the graphs build without problems (i.e. no out-of-memory errors).
• 11. For new features or changes involving the graphbuilding process (i.e. changing encoders, updating the
  importer etc.), I have generated longer distance routes for the affected profiles with different options
  (avoid features, max weight etc.) and compared these with the routes of the same parameters and start/end
  points generated from the current live ORS.
  If there are differences then the reasoning for these MUST be documented in the pull request.
• 12. I have written in the Pull Request information about the changes made including their intended usage
  and why the change was needed.
• 13. For changes touching the API documentation, I have tested that the API playground renders correctly.

Fixes #2084.

Information about the changes

• Key functionality added: Documentation on the fields of Json and Geojson responses of the directions endpoint.
• Reason for change: Documentation was requested.

Examples and reasons for differences between live ORS routes, and those generated from this pull request

Required changes to ors config (if applicable)

[aoles]

Thanks a lot for the prompt fix! ❤️

Do you think we could include the description in the interactive docs (aka API Playground) as well? Cheers! 🙏

[aoles]

Thanks a lot for documenting the missing bits! 🙏

We should probably verify the changes on staging before the merge.

[aoles]

Thanks again for for adding the descriptions 👍 I've noticed that properties and segments are still missing them, do you think you could still fix this?

Please find some additional points for your consideration in my comments below. Cheers! 🤟

[aoles]

The geometry field of a GeoJSON feature incorrectly shows up under the name GeoJSONGeometry. It is also missing the internal structure, namely the mandatory type field and the coordinates array. Instead, it displays an empty boolean field. It would be really great if you could look into fixing this ❤️

[merydian]

getGeometry needs to return a JSONObject and thus cannot be switched with a fitting subclass to display type and coordinates in the docs. I haven't found a way yet to make it display anyways.

[aoles]

Thanks for your efforts! ❤️ I think this could be solved by implementing a dedicated GeoJSONGeometry class containing the required fields properly annotated and described. You might want to introduce such class matching the following replacement code. Let JSONWarning class or similar serve you as a template.

@Schema(name = "geometry", description = "The geometry of the route formatted as a GeoJSON LineString.")
@JsonProperty("geometry")
public GeoJSONGeometry getGeometry() {
    return new GeoJSONGeometry("LineString", GeometryJSON.toJSON(this.routeCoordinates, includeElevation));
}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud