Added docs for API documentation.

Documentation/Books/Users/Foxx/Develop/ApiDocumentation.mdpp

@@ -0,0 +1,9 @@
+!CHAPTER Foxx API Documentation
+
+In addition to viewing the API documentation of any Foxx app in the admin frontend, you can also mount the API
+documentation inside your own Foxx app. This allows you to serve your documentation to users without having to
+give them access to the admin frontend or any other parts of ArangoDB.
+
+!SECTION Mounting the API documentation
+<!-- js/server/modules/org/arangodb/foxx/controller.js -->
+@startDocuBlock JSF_foxx_controller_apiDocumentation

Documentation/Books/Users/SUMMARY.md

@@ -113,6 +113,7 @@
     * [Background Tasks](Foxx/Develop/Queues.md)
     * [Console API](Foxx/Develop/Console.md)
     * [Metainformation](Foxx/Develop/Manifest.md)
+    * [Documentation](Foxx/Develop/ApiDocumentation.md)
   * [Production](Foxx/Production/README.md)
     * [Prod-Mode](Foxx/Production/Productionmode.md)
     * [Debugging](Foxx/Production/Debugging.md)

js/server/modules/org/arangodb/foxx/controller.js

@@ -753,7 +753,63 @@ extend(Controller.prototype, {
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_foxx_controller_apiDocumentation
 ///
-/// `FoxxController#apiDocumentation(path, opts)`
+/// `FoxxController#apiDocumentation(path, [opts])`
+///
+/// Mounts the API documentation (Swagger) at the given *path*.
+///
+/// Note that the **path** can use URL parameters as usual but must not use any
+/// wildcard (`*`) or optional (`:name?`) parameters.
+///
+/// The optional **opts** can be an object with any of the following properties:
+///
+/// * **before**: a function that will be executed before a request to
+///   this endpoint is processed further.
+/// * **appPath**: the mount point of the app for which documentation will be
+///   shown. Default: the mount point of the active app.
+/// * **indexFile**: file path or file name of the Swagger HTML file.
+///   Default: `"index.html"`.
+/// * **swaggerJson**: file path or file name of the Swagger API description JSON
+///   file or a function `swaggerJson(req, res, opts)` that sends a Swagger API
+///   description in JSON. Default: the built-in Swagger description generator.
+/// * **swaggerRoot**: absolute path that will be used as the path path for any
+///   relative paths of the documentation assets, **swaggerJson** file and
+///   the **indexFile**. Default: the built-in Swagger distribution.
+///
+/// If **opts** is a function, it will be used as the value of **opts.before**.
+///
+/// If **opts.before** returns `false`, the request will not be processed
+/// further.
+///
+/// If **opts.before** returns an object, any properties will override the
+/// equivalent properties of **opts** for the current request.
+///
+/// Of course all **before**, **after** or **around** functions defined on the
+/// controller will also be executed as usual.
+///
+/// **Examples**
+///
+/// ```js
+/// controller.apiDocumentation('/my/dox');
+///
+/// ```
+///
+/// A request to `/my/dox` will be redirect to `/my/dox/index.html`,
+/// which will show the API documentation of the active app.
+///
+/// ```js
+/// controller.apiDocumentation('/my/dox', function (req, res) {
+///   if (!req.session.get('uid')) {
+///     res.status(403);
+///     res.json({error: 'only logged in users may see the API'});
+///     return false;
+///   }
+///   return {appPath: req.parameters.mount};
+/// });
+/// ```
+///
+/// A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the
+/// API documentation of the admin frontend (mounted at `/_admin/aardvark`).
+/// If the user is not logged in, the error message will be shown instead.
 ///
 /// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
@@ -766,11 +822,11 @@ extend(Controller.prototype, {
   },
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_foxx_controller_destroySession
+/// @startDocuBlock JSF_foxx_controller_extend
 ///
 /// `FoxxController#extend(extensions)`
 ///
-/// @EXAMPLES
+/// **Examples**
 ///
 /// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////