Merging to release-5.8: [TT-11387] Unhelpful error messages in UI when creating APIs via OpenAPI import (#7067)

[TT-11387] Unhelpful error messages in UI when creating APIs via OpenAPI import (#7067)

### **User description**
<details open>
<summary><a href="https://tyktech.atlassian.net/browse/TT-11387"
title="TT-11387" target="_blank">TT-11387</a></summary>
  <br />
  <table>
    <tr>
      <th>Summary</th>
<td>Unhelpful error messages in UI when creating APIs via OpenAPI
import</td>
    </tr>
    <tr>
      <th>Type</th>
      <td>
<img alt="Bug"
src="https://tyktech.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium"
/>
        Bug
      </td>
    </tr>
    <tr>
      <th>Status</th>
      <td>In Dev</td>
    </tr>
    <tr>
      <th>Points</th>
      <td>N/A</td>
    </tr>
    <tr>
      <th>Labels</th>
<td><a
href="https://tyktech.atlassian.net/issues?jql=project%20%3D%20TT%20AND%20labels%20%3D%20codilime_refined%20ORDER%20BY%20created%20DESC"
title="codilime_refined">codilime_refined</a></td>
    </tr>
  </table>
</details>
<!--
  do not remove this marker as it will break jira-lint's functionality.
  added_by_jira_lint
-->

---

<!-- Provide a general summary of your changes in the Title above -->

## Description

When importing an OpenAPI Document into Tyk, users encounter cryptic
error messages that don't provide clear guidance on how to resolve the
issues. This is particularly problematic for the "servers object is
empty in OAS" error, which occurs when importing an OpenAPI Document
without a servers section. Users aren't informed that they can use the
Custom Upstream URL option as an alternative to modifying their OpenAPI
Document.

## Related Issue

<!-- This project only accepts pull requests related to open issues. -->
<!-- If suggesting a new feature or change, please discuss it in an
issue first. -->
<!-- If fixing a bug, there should be an issue describing it with steps
to reproduce. -->
<!-- OSS: Please link to the issue here. Tyk: please create/link the
JIRA ticket. -->

## Motivation and Context

<!-- Why is this change required? What problem does it solve? -->

## How This Has Been Tested

<!-- Please describe in detail how you tested your changes -->
<!-- Include details of your testing environment, and the tests -->
<!-- you ran to see how your change affects other areas of the code,
etc. -->
<!-- This information is helpful for reviewers and QA. -->

## Screenshots (if appropriate)

## Types of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Refactoring or add test (improvements in base code or adds test
coverage to functionality)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply -->
<!-- If there are no documentation updates required, mark the item as
checked. -->
<!-- Raise up any additional concerns not covered by the checklist. -->

- [ ] I ensured that the documentation is up to date
- [ ] I explained why this PR updates go.mod in detail with reasoning
why it's required
- [ ] I would like a code coverage CI quality gate exception and have
explained why


___

### **PR Type**
Bug fix, Tests


___

### **Description**
- Improved error messages for OpenAPI import failures.

- Updated error constants to provide actionable guidance.

- Enhanced test cases to check for new error messages.

- Clarified user instructions for missing or invalid OAS fields.


___



### **Changes walkthrough** 📝
<table><thead><tr><th></th><th align="left">Relevant
files</th></tr></thead><tbody><tr><td><strong>Bug
fix</strong></td><td><table>
<tr>
  <td>
    <details>
<summary><strong>default.go</strong><dd><code>Enhanced and clarified OAS
import error messages</code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; </dd></summary>
<hr>

apidef/oas/default.go

<li>Replaced vague error messages with detailed, user-friendly
<br>explanations.<br> <li> Updated error constants to suggest actionable
next steps.<br> <li> Clarified error context for missing or invalid OAS
fields.<br> <li> Adjusted invalid server URL format message for clarity.


</details>


  </td>
<td><a
href="https://github.com/TykTechnologies/tyk/pull/7067/files#diff-83c3a85bdd05785178ee519b05b1fe2008435dc4ae9448d72b080b5f67c491ad">+5/-5</a>&nbsp;
&nbsp; &nbsp; </td>

</tr>
</table></td></tr><tr><td><strong>Tests</strong></td><td><table>
<tr>
  <td>
    <details>
<summary><strong>api_test.go</strong><dd><code>Updated tests for
improved OAS error messages</code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </dd></summary>
<hr>

gateway/api_test.go

<li>Updated test assertions to match new, more informative error
messages.<br> <li> Ensured tests check for actionable guidance in error
responses.<br> <li> Improved test coverage for OAS import error
scenarios.


</details>


  </td>
<td><a
href="https://github.com/TykTechnologies/tyk/pull/7067/files#diff-10b4a3d7bdd8d98e48b288d27fd46d9ee436617806c46913fdf7942c0e4a992e">+7/-3</a>&nbsp;
&nbsp; &nbsp; </td>

</tr>
</table></td></tr></tr></tbody></table>

___

> <details> <summary> Need help?</summary><li>Type <code>/help how to
...</code> in the comments thread for any questions about PR-Agent
usage.</li><li>Check out the <a
href="https://qodo-merge-docs.qodo.ai/usage-guide/">documentation</a>
for more information.</li></details>

Author: buger

apidef/oas/default.go

@@ -13,7 +13,7 @@ import (
 )
 
 const (
-	invalidServerURLFmt          = "Please update %q to be a valid URL or pass a valid URL with upstreamURL query param"
+	invalidServerURLFmt          = "Please update %q to be a valid URL and try again."
 	unsupportedSecuritySchemeFmt = "unsupported security scheme: %s"
 
 	middlewareValidateRequest = "validateRequest"
@@ -22,10 +22,10 @@ const (
 )
 
 var (
-	errEmptyServersObject  = errors.New("servers object is empty in OAS")
-	errEmptySecurityObject = errors.New("security object is empty in OAS")
-	errInvalidUpstreamURL  = errors.New("invalid upstream URL")
-	errInvalidServerURL    = errors.New("error validating servers entry in OAS")
+	errEmptyServersObject  = errors.New("The ‘servers’ object is empty in your OAS. You can either add a ‘servers’ section to your OpenAPI description or provide a Custom Upstream URL in the manual configuration options below.")
+	errEmptySecurityObject = errors.New("The ‘security’ object is empty in your OAS. When enabling authentication, your OpenAPI description must include a ‘security’ object that defines the authentication schemes. You can either add a ‘security’ object or disable authentication in the API settings.")
+	errInvalidUpstreamURL  = errors.New("The manually configured upstream URL is not valid. The URL must be absolute and properly formatted (e.g. https://example.com). Please check the URL format and try again.")
+	errInvalidServerURL    = errors.New("The first entry in the ‘servers’ object of your OAS in not valid. The URL must be absolute and properly formatted (e.g. https://example.com).")
 
 	allowedMethods = []string{
 		http.MethodConnect,

gateway/api_test.go

@@ -3222,7 +3222,9 @@ func TestOAS(t *testing.T) {
 
 			_, _ = ts.Run(t, []test.TestCase{
 				{AdminAuth: true, Method: http.MethodPatch, Path: patchPath, Data: &apiInOAS,
-					QueryParams: params, BodyMatch: `"message":"invalid upstream URL"`, Code: http.StatusBadRequest},
+					QueryParams: params,
+					BodyMatch:   `The manually configured upstream URL is not valid. The URL must be absolute and properly formatted \(e.g. https://example.com\). Please check the URL format and try again.`,
+					Code:        http.StatusBadRequest},
 			}...)
 		})
 
@@ -3519,15 +3521,17 @@ func TestOAS(t *testing.T) {
 			newParam.UpstreamURL = "upstream.example.com"
 			params := configParams(newParam)
 			_ = testImportOAS(t, ts, test.TestCase{QueryParams: params,
-				Code: http.StatusBadRequest, Data: oasCopy(false, nil), AdminAuth: true, BodyMatch: "invalid upstream URL",
+				Code: http.StatusBadRequest, Data: oasCopy(false, nil), AdminAuth: true,
+				BodyMatch: `The manually configured upstream URL is not valid. The URL must be absolute and properly formatted \(e.g. https://example.com\). Please check the URL format and try again.`,
 			})
 		})
 
 		t.Run("missing upstream URL", func(t *testing.T) {
 			oasAPI := oasCopy(false, func(t *openapi3.T) {
 				t.Servers = openapi3.Servers{}
 			})
-			_ = testImportOAS(t, ts, test.TestCase{Code: http.StatusBadRequest, Data: oasAPI, AdminAuth: true, BodyMatch: "servers object is empty in OAS"})
+			_ = testImportOAS(t, ts, test.TestCase{Code: http.StatusBadRequest, Data: oasAPI, AdminAuth: true,
+				BodyMatch: "The ‘servers’ object is empty in your OAS. You can either add a ‘servers’ section to your OpenAPI description or provide a Custom Upstream URL in the manual configuration options below."})
 		})
 
 		t.Run("success without config query params, no tyk ext", func(t *testing.T) {