From 8ef7ff860a8eebac1b13f9a7fa59289f76af03be Mon Sep 17 00:00:00 2001 From: jill-cardamon <43434254+jill-cardamon@users.noreply.github.com> Date: Thu, 20 Jan 2022 13:38:59 -0800 Subject: [PATCH] Add documentation for MapboxDirectionsCLI tool (#586) * Add initial doc file. * Fix docs. * Incorporate feedback. --- CommandLineTool.md | 43 ++++++++++++++++++++++ MapboxDirections.xcodeproj/project.pbxproj | 2 + README.md | 2 + 3 files changed, 47 insertions(+) create mode 100644 CommandLineTool.md diff --git a/CommandLineTool.md b/CommandLineTool.md new file mode 100644 index 000000000..4e2ddf22f --- /dev/null +++ b/CommandLineTool.md @@ -0,0 +1,43 @@ +# Mapbox Directions Command Line Tool + +## Getting Started +`mapbox-directions-swift` is a command line tool, designed to round-trip an arbitrary, JSON-formatted Directions or Map Matching API response through model objects and back to JSON. This is useful for various scenarios including testing purposes and designing more sophisticated API response processing pipelines. It is supplied as a Swift package. + +To build `MapboxDirectionsCLI` using SPM: + +1. `swift build` + +To run (and build if it wasn't yet) `MapboxDirectionsCLI` and see usage: + +1. `swift run mapbox-directions-swift -h` + +To run the `MapboxDirectionsCLI` within Xcode, select the `MapboxDirectionsCLI` target and edit the scheme to include arguments passed at launch. + +## Usage and Recipes + +`mapbox-directions-swift` is a useful tool for mobile quality assurance. This tool can be used to verify a response to ensure proper Directions API integration, get a [GPX](https://wikipedia.org/wiki/GPS_Exchange_Format) trace that can be used in the Xcode Simulator, and convert a Directions API request to an Options object. + +### Options +`--input` +An optional flag for the filepath to the input JSON. If this flag is not used, `mapbox-directions-swift` will fallback to a Directions API request. To request using specific coordinates, specify coordinates using `--waypoints` or a Directions API request using `--url`. + +`--config` +An optional flag for the filepath to the JSON, containing serialized Options data. + +`--output` +An optional flag for the filepath to save the conversion result. If no filepath is provided, the result will output to the shell. If you want a GPX trace that can be easily uploaded to Xcode, provide an output filepath with this flag. + +`--format` +An optional flag for the output format. `mapbox-directions-swift` supports text, json, and gpx formats. If you want to simulate a route within the Xcode simulator, you will need a GPX trace. This tool can return a route response as in Xcode-compatible GPX format by using the following recipe: To get a GPX trace that can be used in the Xcode simulator, you can use the following recipe: +``` +swift run mapbox-directions-swift route -c < PATH TO CONFIG FILE (with your RouteOptions JSON) > -f gpx -i < PATH TO INPUT FILE (with your Directions API response) > -o < PATH TO OUTPUT FILE > +``` + +`--url` +If you want an alternative to the JSON input file, you can provide a Directions API request URL string to the command line tool. For example, +``` +swift run mapbox-directions-swift route -c < PATH TO CONFIG FILE (with your RouteOptions JSON) > -f text -i < PATH TO INPUT FILE (with your Directions API response) > -u < URL REQUEST STRING > +``` + + + diff --git a/MapboxDirections.xcodeproj/project.pbxproj b/MapboxDirections.xcodeproj/project.pbxproj index 050ffd693..884c8a8b3 100644 --- a/MapboxDirections.xcodeproj/project.pbxproj +++ b/MapboxDirections.xcodeproj/project.pbxproj @@ -524,6 +524,7 @@ AEAB390C20D7F4F4008F4E54 /* subLaneInstructions.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = subLaneInstructions.json; sourceTree = ""; }; AEAB391020D94699008F4E54 /* subVisualInstructions.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = subVisualInstructions.json; sourceTree = ""; }; AEDC211C20B6104A0052DED8 /* VisualInstructionComponent.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = VisualInstructionComponent.swift; sourceTree = ""; }; + C34502DD27568E4C005FE26F /* CommandLineTool.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = CommandLineTool.md; sourceTree = ""; }; C51538CB1E807FF00093FF3E /* AttributeOptions.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AttributeOptions.swift; sourceTree = ""; }; C5247D701E818A24004B6154 /* AnnotationTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AnnotationTests.swift; sourceTree = ""; }; C52552B81FA15D5900B1545C /* VisualInstructionBanner.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = VisualInstructionBanner.swift; sourceTree = ""; }; @@ -718,6 +719,7 @@ 8A41B0FC24F5C2390021FFDC /* CHANGELOG.md */, 438BFEBC233D7FA900457294 /* Package.swift */, 438BFEC0233D805500457294 /* README.md */, + C34502DD27568E4C005FE26F /* CommandLineTool.md */, ); name = Documents; sourceTree = ""; diff --git a/README.md b/README.md index 79166a156..5ba3fae55 100644 --- a/README.md +++ b/README.md @@ -282,6 +282,8 @@ To run (and build if it wasn't yet) `MapboxDirectionsCLI` and see usage: 1. `swift run mapbox-directions-swift -h` +For further details, see the [MapboxDirectionsCLI documentation](CommandLineTool.md). + ## Pricing API calls made to the Directions API are individually billed by request. Review the [pricing information](https://docs.mapbox.com/api/navigation/directions/#directions-api-pricing) and the [pricing page](https://www.mapbox.com/pricing/#directions) for current rates.