Add latest changes from gitlab-org/gitlab@14-7-stable-eev14.7.0-rc42

1 files changed, 38 insertions, 2 deletions

diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md
index 0db5fb2d868..f1eba505589 100644
--- a/doc/user/application_security/dast_api/index.md
+++ b/doc/user/application_security/dast_api/index.md
@@ -214,7 +214,7 @@ target API to test:
      DAST_API_PROFILE: Quick
    ```
 
-1. Provide the location of the HAR specification. You can provide the specification as a file
+1. Provide the location of the HAR file. You can provide the location as a file path
    or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable:
 
    ```yaml
@@ -314,7 +314,7 @@ information about the target API to test:
      DAST_API_PROFILE: Quick
    ```
 
-1. Provide the location of the Postman Collection specification. You can provide the specification as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable:
+1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable:
 
    ```yaml
    stages:
@@ -637,6 +637,7 @@ can be added, removed, and modified by creating a custom configuration.
 |[`DAST_API_PROFILE`](#configuration-files)             | Configuration profile to use during testing. Defaults to `Quick`. |
 |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths)              | Exclude API URL paths from testing. |
 |[`DAST_API_OPENAPI`](#openapi-specification)           | OpenAPI specification file or URL. |
+|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. |
 |[`DAST_API_HAR`](#http-archive-har)                    | HTTP Archive (HAR) file. |
 |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection)   | Postman Collection file. |
 |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. |
@@ -1209,6 +1210,41 @@ deploy-test-target:
       - environment_url.txt
 ```
 
+### Use OpenAPI with an invalid schema
+
+There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors.
+
+#### Edit a non-compliant OpenAPI file
+
+To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include:
+
+| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
+| -- | -- | -- | -- |
+| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON |
+| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON |
+
+If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using.
+
+#### Enable OpenAPI relaxed validation
+
+Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema.
+
+API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example:
+
+```yaml
+   stages:
+     - dast
+
+   include:
+     - template: DAST-API.gitlab-ci.yml
+
+   variables:
+     DAST_API_PROFILE: Quick
+     DAST_API_TARGET_URL: http://test-deployment/
+     DAST_API_OPENAPI: test-api-specification.json
+     DAST_API_OPENAPI_RELAXED_VALIDATION: On
+```
+
 ## Get support or request an improvement
 
 To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/).