Amend docs

big_tests/tests/rest_helper.erl

@@ -281,8 +281,13 @@ insert_creds(Opts = #{handlers := Handlers}, Creds) ->
     NewHandlers = [inject_creds_to_opts(Handler, Creds) || Handler <- Handlers],
     Opts#{handlers := NewHandlers}.
 
-inject_creds_to_opts(Handler = #{module := mongoose_api_admin}, {UserName, Password}) ->
-    Handler#{username => UserName, password => Password};
+inject_creds_to_opts(Handler = #{module := mongoose_api_admin}, Creds) ->
+    case Creds of
+        {UserName, Password} ->
+            Handler#{username => UserName, password => Password};
+        any ->
+            maps:without([username, password], Handler)
+    end;
 inject_creds_to_opts(Handler, _Creds) ->
     Handler.
 

doc/configuration/listen.md

@@ -420,11 +420,11 @@ Recommended port number: 5280 for BOSH/WS.
 There are the following options for each of the HTTP listeners:
 
 ### `listen.http.handlers`
-* **Syntax:** each handler is specified in a subsection starting with `[[listen.http.handlers.type]]` where `type` is one of the allowed handler types, handling different connection types, e.g.
+* **Syntax:** each handler is specified in a subsection starting with `[[listen.http.handlers.type]]` where `type` is one of the allowed handler types, handling different connection types:
 
     * `mod_bosh` - for [BOSH](https://xmpp.org/extensions/xep-0124.html) connections,
     * `mod_websockets` - for [WebSocket](https://tools.ietf.org/html/rfc6455) connections,
-    * `mongoose_api_*`, `mongoose_client_api_*`, ... - for REST API.
+    * `mongoose_api_admin`, `mongoose_client_api`, `mongoose_domain_handler`, `mongoose_api` - for REST API.
 
     These types are described below in more detail.
     The double-bracket syntax is used because there can be multiple handlers of a given type, so for each type there is a TOML array of one or more tables (subsections).
@@ -459,10 +459,12 @@ Path for this handler.
 
 ### Handler types: BOSH - `mod_bosh`
 
+The recommended configuration is shown in [Example 1](#example-1-bosh-and-ws) below.
 To handle incoming BOSH traffic you need to configure the `mod_bosh` module in the `modules` section as well.
 
 ### Handler types: WebSockets - `mod_websockets`
 
+The recommended configuration is shown in [Example 1](#example-1-bosh-and-ws) below.
 Websocket connections as defined in [RFC 7395](https://tools.ietf.org/html/rfc7395).
 You can pass the following optional parameters:
 
@@ -506,6 +508,7 @@ See the [service](#xmpp-components-listenservice) listener section for details.
 
 ### Handler types: REST API - Admin - `mongoose_api_admin`
 
+The recommended configuration is shown in [Example 2](#example-4-admin-api) below.
 For more information about the API, see the [REST interface](../rest-api/Administration-backend.md) documentation.
 The following options are supported for this handler:
 
@@ -523,19 +526,32 @@ When set, enables authentication for the admin API, otherwise it is disabled. Re
 
 Required to enable authentication for the admin API.
 
-### Handler types: REST API - Client
-
-To enable the REST API for clients, several handlers need to be added:
-
-* `mongoose_client_api_*` - handles individual API endpoints. You can add and remove these to enable particular functionality.
-* `lasse_handler` - provides the [SSE handler](https://github.com/inaka/lasse) which is required for the client HTTP API, should not be changed.
-* `cowboy_*` - hosts the Swagger web-based documentation, should not be changed, but can be removed to disable the API docs.
+### Handler types: REST API - Client - `mongoose_client_api`
 
 The recommended configuration is shown in [Example 3](#example-3-client-api) below.
 Please refer to [REST interface](../rest-api/Client-frontend.md) documentation for more information.
+The following options are supported for this handler:
+
+#### `listen.http.handlers.mongoose_client_api.handlers`
+* **Syntax:** an array of strings - Erlang modules
+* **Default:** all API handler modules enabled
+* **Example:** `modules = ["mongoose_client_api_messages", "mongoose_client_api_sse"]`
+
+The client API consists of several modules, each of them implementing a subset of the functionality.
+By default all modules are enabled, so you don't need to change this option.
+For a list of allowed modules, you need to consult the [source code](https://github.com/esl/MongooseIM/blob/master/src/mongoose_client_api/mongoose_client_api.erl).
+
+#### `listen.http.handlers.mongoose_client_api.docs`
+* **Syntax:** boolean
+* **Default:** `true`
+* **Example:** `docs = "false"`
+
+By default the Swagger documentation is hosted at the `/doc` sub-path (e.g. `/api/doc` if `/api` is used for the client API).
+You can disable the hosted documentation by setting this option to `false`.
 
 ### Handler types: REST API - Domain management - `mongoose_domain_handler`
 
+The recommended configuration is shown in [Example 4](#example-4-domain-api) below.
 This handler enables dynamic domain management for different host types.
 For more information about the API, see the [REST interface](../rest-api/Dynamic-domains.md) documentation.
 The following options are supported for this handler:
@@ -562,7 +578,7 @@ The following option is required:
 
 #### `listen.http.handlers.mongoose_api.handlers`
 * **Syntax:** array of strings - Erlang modules
-* **Default:** not set, this is a mandatory option for this handler
+* **Default:** all API handler modules enabled
 * **Example:** `handlers = ["mongoose_api_metrics"]`
 
 ### Transport options
@@ -720,49 +736,9 @@ REST API for clients.
   transport.max_connections = 1024
   protocol.compress = true
 
-  [[listen.http.handlers.lasse_handler]]
-    host = "_"
-    path = "/api/sse"
-    module = "mongoose_client_api_sse"
-
-  [[listen.http.handlers.mongoose_client_api_messages]]
-    host = "_"
-    path = "/api/messages/[:with]"
-
-  [[listen.http.handlers.mongoose_client_api_contacts]]
-    host = "_"
-    path = "/api/contacts/[:jid]"
-
-  [[listen.http.handlers.mongoose_client_api_rooms]]
-    host = "_"
-    path = "/api/rooms/[:id]"
-
-  [[listen.http.handlers.mongoose_client_api_rooms_config]]
-    host = "_"
-    path = "/api/rooms/[:id]/config"
-
-  [[listen.http.handlers.mongoose_client_api_rooms_users]]
-    host = "_"
-    path = "/api/rooms/:id/users/[:user]"
-
-  [[listen.http.handlers.mongoose_client_api_rooms_messages]]
+  [[listen.http.handlers.mongoose_client_api]]
     host = "_"
-    path = "/api/rooms/[:id]/messages"
-
-  [[listen.http.handlers.cowboy_swagger_redirect_handler]]
-    host = "_"
-    path = "/api-docs"
-
-  [[listen.http.handlers.cowboy_swagger_json_handler]]
-    host = "_"
-    path = "/api-docs/swagger.json"
-
-  [[listen.http.handlers.cowboy_static]]
-    host = "_"
-    path = "/api-docs/[...]"
-    type = "priv_dir"
-    app = "cowboy_swagger"
-    content_path = "swagger"
+    path = "/api"
 ```
 
 #### Example 4. Domain API