Merge branch '298849-add-trouble-shooting-entry-for-schema-errors' into 'master'

Add troubleshoot section

See merge request gitlab-org/gitlab!58591

doc/user/application_security/api_fuzzing/index.md

@@ -1145,6 +1145,35 @@ Profiles:
 
 ## Troubleshooting
 
+### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema
+
+At the start of an API Fuzzing job the OpenAPI specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI specification has validation errors. Errors can be introduced when creating an OpenAPI specification manually, and also when the schema is generated.
+
+For OpenAPI specifications that are generated automatically validation errors are often the result of missing code annotations.
+
+**Error message**
+
+- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema`
+  - `OpenAPI 2.0 schema validation error ...`
+  - `OpenAPI 3.0.x schema validation error ...`
+
+**Solution** 
+
+**For generated OpenAPI specifications**
+
+1. Identify the validation errors.
+    1. Use the [Swagger Editor](https://editor.swagger.io/) to identify validation problems in your specification. The visual nature of the Swagger Editor makes it easier to understand what needs to change.
+    1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Note that JSON Schema validation messages might not be easy to understand. This is why we recommend the use of editors to validate schema documents.
+1. Review the documentation for the OpenAPI generation your framework/tech stack is using. Identify the changes needed to produce a correct OpenAPI document.
+1. Once the validation issues are resolved, re-run your pipeline.
+
+**For manually created OpenAPI Specifications**
+
+1. Identify the validation errors.
+   1. The simplest solution is to use a visual tool to edit and validate the OpenAPI document. For example the [Swagger Editor](https://editor.swagger.io/) will point out schema errors and possible solutions.
+   1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Correct each of the validation failures and then resubmit the OpenAPI doc. Note that JSON Schema validation message might not be easy to understand. This is why we recommend the use of editors to validate document.
+1. Once the validation issues are resolved, re-run your pipeline.
+
 ### Failed to start scanner session (version header not found)
 
 The API Fuzzing engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `apifuzzer_fuzz` job. A common cause of this issue is changing the `FUZZAPI_API` variable from its default.