Document custom validation for http request (#47699) (#48203)

* document custom validation for http request

* generate docs

docs/development/core/server/kibana-plugin-server.routeconfig.md

@@ -18,5 +18,5 @@ export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B exten
 |  --- | --- | --- |
 |  [options](./kibana-plugin-server.routeconfig.options.md) | <code>RouteConfigOptions</code> | Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md)<!-- -->. |
 |  [path](./kibana-plugin-server.routeconfig.path.md) | <code>string</code> | The endpoint \_within\_ the router path to register the route. E.g. if the router is registered at <code>/elasticsearch</code> and the route path is <code>/search</code>, the full path for the route is <code>/elasticsearch/search</code>. Supports: - named path segments <code>path/{name}</code>. - optional path segments <code>path/{position?}</code>. - multi-segments <code>path/{coordinates*2}</code>. Segments are accessible within a handler function as <code>params</code> property of [KibanaRequest](./kibana-plugin-server.kibanarequest.md) object. To have read access to <code>params</code> you \*must\* specify validation schema with [RouteConfig.validate](./kibana-plugin-server.routeconfig.validate.md)<!-- -->. |
-|  [validate](./kibana-plugin-server.routeconfig.validate.md) | <code>RouteSchemas&lt;P, Q, B&gt; &#124; false</code> | A schema created with <code>@kbn/config-schema</code> that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify <code>false</code>. |
+|  [validate](./kibana-plugin-server.routeconfig.validate.md) | <code>RouteSchemas&lt;P, Q, B&gt; &#124; false</code> | A schema created with <code>@kbn/config-schema</code> that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify <code>validate: false</code>. In this case request params, query, and body will be \*\*empty\*\* objects and have no access to raw values. In some cases you may want to use another validation library. To do this, you need to instruct the <code>@kbn/config-schema</code> library to output \*\*non-validated values\*\* with setting schema as <code>schema.object({}, { allowUnknowns: true })</code>; |
 

docs/development/core/server/kibana-plugin-server.routeconfig.validate.md

@@ -4,7 +4,7 @@
 
 ## RouteConfig.validate property
 
-A schema created with `@kbn/config-schema` that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify `false`<!-- -->.
+A schema created with `@kbn/config-schema` that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify `validate: false`<!-- -->. In this case request params, query, and body will be \*\*empty\*\* objects and have no access to raw values. In some cases you may want to use another validation library. To do this, you need to instruct the `@kbn/config-schema` library to output \*\*non-validated values\*\* with setting schema as `schema.object({}, { allowUnknowns: true })`<!-- -->;
 
 <b>Signature:</b>
 
@@ -18,7 +18,7 @@ validate: RouteSchemas<P, Q, B> | false;
 ```ts
  import { schema } from '@kbn/config-schema';
  router.get({
-  path: 'path/{id}'
+  path: 'path/{id}',
   validate: {
     params: schema.object({
       id: schema.string(),
@@ -26,7 +26,33 @@ validate: RouteSchemas<P, Q, B> | false;
     query: schema.object({...}),
     body: schema.object({...}),
   },
- })
+},
+(context, req, res,) {
+  req.params; // type Readonly<{id: string}>
+  console.log(req.params.id); // value
+});
+
+router.get({
+  path: 'path/{id}',
+  validate: false, // handler has no access to params, query, body values.
+},
+(context, req, res,) {
+  req.params; // type Readonly<{}>;
+  console.log(req.params.id); // undefined
+});
+
+router.get({
+  path: 'path/{id}',
+  validate: {
+    // handler has access to raw non-validated params in runtime
+    params: schema.object({}, { allowUnknowns: true })
+  },
+},
+(context, req, res,) {
+  req.params; // type Readonly<{}>;
+  console.log(req.params.id); // value
+  myValidationLibrary.validate({ params: req.params });
+});
 
 ```
 

src/core/server/http/router/route.ts

@@ -68,12 +68,17 @@ export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B exten
    *   - url path segments
    *   - request query
    *   - request body
-   * To opt out of validating the request, specify `false`.
+   * To opt out of validating the request, specify `validate: false`. In this case
+   * request params, query, and body will be **empty** objects and have no
+   * access to raw values.
+   * In some cases you may want to use another validation library. To do this, you need to
+   * instruct the `@kbn/config-schema` library to output **non-validated values** with
+   * setting schema as `schema.object({}, { allowUnknowns: true })`;
    * @example
    * ```ts
    *  import { schema } from '@kbn/config-schema';
    *  router.get({
-   *   path: 'path/{id}'
+   *   path: 'path/{id}',
    *   validate: {
    *     params: schema.object({
    *       id: schema.string(),
@@ -81,7 +86,33 @@ export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B exten
    *     query: schema.object({...}),
    *     body: schema.object({...}),
    *   },
-   *  })
+   * },
+   * (context, req, res,) {
+   *   req.params; // type Readonly<{id: string}>
+   *   console.log(req.params.id); // value
+   * });
+   *
+   * router.get({
+   *   path: 'path/{id}',
+   *   validate: false, // handler has no access to params, query, body values.
+   * },
+   * (context, req, res,) {
+   *   req.params; // type Readonly<{}>;
+   *   console.log(req.params.id); // undefined
+   * });
+   *
+   * router.get({
+   *   path: 'path/{id}',
+   *   validate: {
+   *     // handler has access to raw non-validated params in runtime
+   *     params: schema.object({}, { allowUnknowns: true })
+   *   },
+   * },
+   * (context, req, res,) {
+   *   req.params; // type Readonly<{}>;
+   *   console.log(req.params.id); // value
+   *   myValidationLibrary.validate({ params: req.params });
+   * });
    * ```
    */
   validate: RouteSchemas<P, Q, B> | false;