Add connect command, remove set swagger command (#13973)

* Add connect command, remove set swagger command

Also document the `swagger.searchPaths` preference.

* Apply suggestions from code review

Co-Authored-By: Scott Addie <10702007+scottaddie@users.noreply.github.com>

aspnetcore/web-api/http-repl.md

@@ -76,6 +76,12 @@ Options:
 
 Once the REPL starts, these commands are valid:
 
+Setup Commands:
+Use these commands to configure the tool for your API server
+
+connect        Configures the directory structure and base address of the api server
+set header     Sets or clears a header for all requests. e.g. `set header content-type application/json`
+
 HTTP Commands:
 Use these commands to execute requests against your application.
 
@@ -87,13 +93,10 @@ PATCH          patch - Issues a PATCH request
 HEAD           head - Issues a HEAD request
 OPTIONS        options - Issues a OPTIONS request
 
-set header     Sets or clears a header for all requests. e.g. `set header content-type application/json`
-
 Navigation Commands:
 The REPL allows you to navigate your URL space and focus on specific APIs that you are working on.
 
 set base       Set the base URI. e.g. `set base http://locahost:5000`
-set swagger    Sets the swagger document to use for information about the current server
 ls             Show all endpoints for the current path
 cd             Append the given directory to the currently selected path, or move up a path when using `cd ..`
 
@@ -122,10 +125,10 @@ The HTTP REPL offers command completion. Pressing the <kbd>Tab</kbd> key iterate
 Connect to a web API by running the following command:
 
 ```console
-dotnet httprepl <BASE URI>
+dotnet httprepl <ROOT URI>
 ```
 
-`<BASE URI>` is the base URI for the web API. For example:
+`<ROOT URI>` is the base URI for the web API. For example:
 
 ```console
 dotnet httprepl https://localhost:5001
@@ -134,27 +137,27 @@ dotnet httprepl https://localhost:5001
 Alternatively, run the following command at any time while the HTTP REPL is running:
 
 ```console
-set base <BASE URI>
+connect <ROOT URI>
 ```
 
 For example:
 
 ```console
-(Disconnected)~ set base https://localhost:5001
+(Disconnected)~ connect https://localhost:5001
 ```
 
-## Point to the Swagger document for the web API
+## Manually point to the Swagger document for the web API
 
-To properly inspect the web API, set the relative URI to the Swagger document for the web API. Run the following command:
+The connect command above will attempt to find the Swagger document automatically. If for some reason it is unable to do so, you can specify the URI of the Swagger document for the web API by using the `--swagger` option:
 
 ```console
-set swagger <RELATIVE URI>
+connect <ROOT URI> --swagger <SWAGGER URI>
 ```
 
 For example:
 
 ```console
-https://localhost:5001/~ set swagger /swagger/v1/swagger.json
+(Disconnected)~ connect https://localhost:5001 --swagger /swagger/v1/swagger.json
 ```
 
 ## Navigate the web API
@@ -398,6 +401,21 @@ To launch the default text editor with specific CLI arguments, set the `editor.c
 pref set editor.command.default.arguments "--disable-extensions --new-window"
 ```
 
+### Set the Swagger search paths
+
+By default, the HTTP REPL has a set of relative paths that it uses to find the Swagger document when executing the `connect` command without the `--swagger` option. These relative paths are combined with the root and base paths specified in the `connect` command. The default relative paths are:
+
+- *swagger.json*
+- *swagger/v1/swagger.json*
+- */swagger.json*
+- */swagger/v1/swagger.json*
+
+To use a different set of search paths in your environment, set the `swagger.searchPaths` preference. The value must be a pipe-delimited list of relative paths. For example:
+
+```console
+pref set swagger.searchPaths "swagger/v2/swagger.json|swagger/v3/swagger.json
+```
+
 ## Test HTTP GET requests
 
 ### Synopsis