Finalize Router/Endpoints.md

Documentation/Books/Manual/Foxx/Router/Endpoints.mdpp

@@ -1,6 +1,8 @@
 !CHAPTER Endpoints
 
-TODO
+Endpoints are returned by the `use`, `all` and HTTP verb (e.g. `get`, `post`) methods of [routers](./README.md) as well as the `use` method of the [service context](../Context.md). They can be used to attach metadata to mounted routes, middleware and child routers that affects how requests and responses are processed or provides API documentation.
+
+Endpoints should only be used to invoke the following methods. Endpoint methods can be chained together (each method returns the endpoint itself).
 
 !SECTION header
 
@@ -8,22 +10,24 @@ TODO
 
 Defines a request header recognized by the endpoint. Any additional non-defined headers will be treated as optional string values. The definitions will also be shown in the route details in the API documentation.
 
-If the endpoint is a child router, all routes of that router will use this header definition unless overridden. If the endpoint is a middleware, this method has no effect.
+If the endpoint is a child router, all routes of that router will use this header definition unless overridden.
 
 
 **Arguments**
 
 * **name**: `string`
 
-  TODO
+  Name of the header. This should be considered case insensitive as all header names will be converted to lowercase.
 
 * **schema**: `Schema` (optional)
 
-  TODO
+  A schema describing the format of the header value. This can be a joi schema or anything that has a compatible `validate` method.
+
+  The value of this header will be set to the `value` property of the validation result. A validation failure will result in an automatic 400 (Bad Request) error response.
 
 * **description**: `string` (optional)
 
-  TODO
+  A human readable string that will be shown in the API documentation.
 
 Returns the endpoint.
 
@@ -40,21 +44,23 @@ router.get(/* ... */)
 
 Defines a path parameter recognized by the endpoint. Path parameters are expected to be filled as part of the endpoint's mount path. Any additional non-defined path parameters will be treated as optional string values. The definitions will also be shown in the route details in the API documentation.
 
-If the endpoint is a child router, all routes of that router will use this header definition unless overridden. If the endpoint is a middleware, this method has no effect.
+If the endpoint is a child router, all routes of that router will use this parameter definition unless overridden.
 
 **Arguments**
 
 * **name**: `string`
 
-  TODO
+  Name of the parameter.
 
 * **schema**: `Schema` (optional)
 
-  TODO
+  A schema describing the format of the parameter. This can be a joi schema or anything that has a compatible `validate` method.
+
+  The value of this parameter will be set to the `value` property of the validation result. A validation failure will result in the route failing to match and being ignored (resulting in a 404 (Not Found) error response if no other routes match).
 
 * **description**: `string` (optional)
 
-  TODO
+  A human readable string that will be shown in the API documentation.
 
 Returns the endpoint.
 
@@ -71,21 +77,23 @@ router.get('/some/:num/here', /* ... */)
 
 Defines a query parameter recognized by the endpoint. Any additional non-defined query parameters will be treated as optional string values. The definitions will also be shown in the route details in the API documentation.
 
-If the endpoint is a child router, all routes of that router will use this header definition unless overridden. If the endpoint is a middleware, this method has no effect.
+If the endpoint is a child router, all routes of that router will use this parameter definition unless overridden.
 
 **Arguments**
 
 * **name**: `string`
 
-  TODO
+  Name of the parameter.
 
 * **schema**: `Schema` (optional)
 
-  TODO
+  A schema describing the format of the parameter. This can be a joi schema or anything that has a compatible `validate` method.
+
+  The value of this parameter will be set to the `value` property of the validation result. A validation failure will result in an automatic 400 (Bad Request) error response.
 
 * **description**: `string` (optional)
 
-  TODO
+  A human readable string that will be shown in the API documentation.
 
 Returns the endpoint.
 
@@ -100,21 +108,41 @@ router.get(/* ... */)
 
 `endpoint.body([model], [mimes], [description]): this`
 
-TODO
+Defines the request body recognized by the endpoint. There can only be one request body definition per endpoint. The definition will also be shown in the route details in the API documentation.
+
+If the endpoint is a child router, all routes of that router will use this body definition unless overridden. If the endpoint is a middleware, the request body will only be parsed once (i.e. the MIME types of the route matching the same request will be ignored but the body will still be validated again).
 
 **Arguments**
 
-* **model**: `Model | Schema` (optional)
+* **model**: `Model | Schema | null` (optional)
 
-  TODO
+  A model or joi schema describing the request body. A validation failure will result in an automatic 400 (Bad Request) error response.
+
+  If the value is a model with a `fromClient` method, that method will be applied to the parsed request body.
+
+  If the value is a schema or a model with a schema, the schema will be used to validate the request body and the `value` property of the validation result of the parsed request body will be used instead of the parsed request body itself.
+
+  If the value is a model or a schema and the MIME type has been omitted, the MIME type will default to JSON instead.
+
+  If the value is explicitly set to `null`, no request body will be expected.
+
+  If the value is an array containing exactly one model or schema, the request body will be treated as an array of items matching that model or schema.
 
 * **mimes**: `Array<string>` (optional)
 
-  TODO
+  An array of MIME types the route supports.
+
+  Common non-mime aliases like "json" or "html" are also supported and will be expanded to the appropriate MIME type (e.g. "application/json" and "text/html").
+
+  If the MIME type is recognized by Foxx the request body will be parsed into the appropriate structure before being validated. Currently only JSON, `application/x-www-form-urlencoded` and multipart formats are supported in this way.
+
+  If the MIME type indicated in the request headers does not match any of the supported MIME types, the first MIME type in the list will be used instead.
+
+  Failure to parse the request body will result in an automatic 400 (Bad Request) error response.
 
 * **description**: `string` (optional)
 
-  TODO
+  A human readable string that will be shown in the API documentation.
 
 Returns the endpoint.
 
@@ -127,6 +155,9 @@ router.post('/expects/some/json', /* ... */)
   'This implies JSON.'
 );
 
+router.post('/expects/nothing', /* ... */)
+.body(null); // No body allowed
+
 router.post('/expects/some/plaintext', /* ... */)
 .body(['text/plain'], 'This body will be a string.');
 ```

js/server/modules/@arangodb/foxx/router/swagger-context.js

@@ -83,7 +83,7 @@ module.exports = exports = class SwaggerContext {
       ['string', check.validateSchema, 'string'],
       [name, schema, description]
     );
-    this._headers.set(name, {schema, description});
+    this._headers.set(name.toLowerCase(), {schema, description});
     return this;
   }