OAS Improvements (#4708)

* OAS Improvements

* Update docs

.changeset/large-dingos-sit.md

@@ -0,0 +1,8 @@
+---
+'@omnigraph/openapi': minor
+'@graphql-mesh/utils': minor
+---
+
+BREAKING:
+- ":" character is now sanitized as "_" instead of "\_COLON_"
+- If a path starts with a variable like "{" in an OAS operation, "by_" prefix is no longer added.

packages/loaders/openapi/src/utils.ts

@@ -22,6 +22,10 @@ export function getFieldNameFromPath(path: string, method: string, responseTypeS
     }
   }
 
+  if (fieldNameWithoutMethod.startsWith('by_')) {
+    fieldNameWithoutMethod = fieldNameWithoutMethod.replace('by_', '');
+  }
+
   if (allQueryPartsStr) {
     const queryParts = allQueryPartsStr.split('&');
     for (const queryPart of queryParts) {

packages/loaders/openapi/tests/__snapshots__/calendly.test.ts.snap

@@ -179,7 +179,7 @@ type Query {
     "Return entries from the user(s) associated with the provided URIs"
     actor: [URL]
     "Order results by the specified field and direction. List of {field}:{direction} values."
-    sort: [queryInput_activityLog_sort_items] = [occurred_at_COLON_desc]
+    sort: [queryInput_activityLog_sort_items] = [occurred_at_desc]
     "Include entries that occurred after this time (sample time format: \\"2020-01-02T03:04:05.678Z\\"). This time should use the UTC timezone."
     min_occurred_at: DateTime
     "Include entries that occurred prior to this time (sample time format: \\"2020-01-02T03:04:05.678Z\\"). This time should use the UTC timezone."
@@ -1377,16 +1377,16 @@ scalar NonNegativeInt
 scalar queryInput_activityLog_search_term
 
 enum queryInput_activityLog_sort_items {
-  action_COLON_asc
-  action_COLON_desc
-  actor_display_name_COLON_asc
-  actor_display_name_COLON_desc
-  actor_uri_COLON_asc
-  actor_uri_COLON_desc
-  namespace_COLON_asc
-  namespace_COLON_desc
-  occurred_at_COLON_asc
-  occurred_at_COLON_desc
+  action_asc
+  action_desc
+  actor_display_name_asc
+  actor_display_name_desc
+  actor_uri_asc
+  actor_uri_desc
+  namespace_asc
+  namespace_desc
+  occurred_at_asc
+  occurred_at_desc
 }
 
 "Integers that will have a value greater than 0."

packages/loaders/openapi/tests/__snapshots__/schemas.test.ts.snap

@@ -161522,9 +161522,9 @@ type Webhook {
 }
 
 enum query_getDynamicWebhooksForApp_oneOf_0_values_items_events_items {
-  jira_COLON_issue_created
-  jira_COLON_issue_updated
-  jira_COLON_issue_deleted
+  jira_issue_created
+  jira_issue_updated
+  jira_issue_deleted
   comment_created
   comment_updated
   comment_deleted
@@ -164079,19 +164079,19 @@ input CustomFieldDefinitionJsonBean_Input {
 
 "The searcher defines the way the field is searched in Jira. For example, *com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher*.  \\nThe search UI (basic search and JQL search) will display different operations and values for the field, based on the field searcher. You must specify a searcher that is valid for the field type, as listed below (abbreviated values shown):\\n\\n *  \`cascadingselect\`: \`cascadingselectsearcher\`\\n *  \`datepicker\`: \`daterange\`\\n *  \`datetime\`: \`datetimerange\`\\n *  \`float\`: \`exactnumber\` or \`numberrange\`\\n *  \`grouppicker\`: \`grouppickersearcher\`\\n *  \`importid\`: \`exactnumber\` or \`numberrange\`\\n *  \`labels\`: \`labelsearcher\`\\n *  \`multicheckboxes\`: \`multiselectsearcher\`\\n *  \`multigrouppicker\`: \`multiselectsearcher\`\\n *  \`multiselect\`: \`multiselectsearcher\`\\n *  \`multiuserpicker\`: \`userpickergroupsearcher\`\\n *  \`multiversion\`: \`versionsearcher\`\\n *  \`project\`: \`projectsearcher\`\\n *  \`radiobuttons\`: \`multiselectsearcher\`\\n *  \`readonlyfield\`: \`textsearcher\`\\n *  \`select\`: \`multiselectsearcher\`\\n *  \`textarea\`: \`textsearcher\`\\n *  \`textfield\`: \`textsearcher\`\\n *  \`url\`: \`exacttextsearcher\`\\n *  \`userpicker\`: \`userpickergroupsearcher\`\\n *  \`version\`: \`versionsearcher\`\\n\\nIf no searcher is provided, the field isn't searchable. However, [Forge custom fields](https://developer.atlassian.com/platform/forge/manifest-reference/modules/#jira-custom-field-type--beta-) have a searcher set automatically, so are always searchable."
 enum mutationInput_createCustomField_input_searcherKey {
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_cascadingselectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_daterange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_datetimerange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_exactnumber
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_exacttextsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_grouppickersearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_labelsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_multiselectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_numberrange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_projectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_textsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_userpickergroupsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_versionsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_cascadingselectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_daterange
+  com_atlassian_jira_plugin_system_customfieldtypes_datetimerange
+  com_atlassian_jira_plugin_system_customfieldtypes_exactnumber
+  com_atlassian_jira_plugin_system_customfieldtypes_exacttextsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_grouppickersearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_labelsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_multiselectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_numberrange
+  com_atlassian_jira_plugin_system_customfieldtypes_projectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_textsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_userpickergroupsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_versionsearcher
 }
 
 union updateCustomField_response = updateCustomField_400_response | updateCustomField_403_response | updateCustomField_404_response
@@ -164122,19 +164122,19 @@ input UpdateCustomFieldDetails_Input {
 
 "The searcher that defines the way the field is searched in Jira. It can be set to \`null\`, otherwise you must specify the valid searcher for the field type, as listed below (abbreviated values shown):\\n\\n *  \`cascadingselect\`: \`cascadingselectsearcher\`\\n *  \`datepicker\`: \`daterange\`\\n *  \`datetime\`: \`datetimerange\`\\n *  \`float\`: \`exactnumber\` or \`numberrange\`\\n *  \`grouppicker\`: \`grouppickersearcher\`\\n *  \`importid\`: \`exactnumber\` or \`numberrange\`\\n *  \`labels\`: \`labelsearcher\`\\n *  \`multicheckboxes\`: \`multiselectsearcher\`\\n *  \`multigrouppicker\`: \`multiselectsearcher\`\\n *  \`multiselect\`: \`multiselectsearcher\`\\n *  \`multiuserpicker\`: \`userpickergroupsearcher\`\\n *  \`multiversion\`: \`versionsearcher\`\\n *  \`project\`: \`projectsearcher\`\\n *  \`radiobuttons\`: \`multiselectsearcher\`\\n *  \`readonlyfield\`: \`textsearcher\`\\n *  \`select\`: \`multiselectsearcher\`\\n *  \`textarea\`: \`textsearcher\`\\n *  \`textfield\`: \`textsearcher\`\\n *  \`url\`: \`exacttextsearcher\`\\n *  \`userpicker\`: \`userpickergroupsearcher\`\\n *  \`version\`: \`versionsearcher\`"
 enum mutationInput_updateCustomField_input_searcherKey {
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_cascadingselectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_daterange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_datetimerange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_exactnumber
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_exacttextsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_grouppickersearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_labelsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_multiselectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_numberrange
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_projectsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_textsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_userpickergroupsearcher
-  com_atlassian_jira_plugin_system_customfieldtypes_COLON_versionsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_cascadingselectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_daterange
+  com_atlassian_jira_plugin_system_customfieldtypes_datetimerange
+  com_atlassian_jira_plugin_system_customfieldtypes_exactnumber
+  com_atlassian_jira_plugin_system_customfieldtypes_exacttextsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_grouppickersearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_labelsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_multiselectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_numberrange
+  com_atlassian_jira_plugin_system_customfieldtypes_projectsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_textsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_userpickergroupsearcher
+  com_atlassian_jira_plugin_system_customfieldtypes_versionsearcher
 }
 
 union createCustomFieldContext_response = CreateCustomFieldContext | createCustomFieldContext_409_response
@@ -166364,28 +166364,28 @@ enum mutationInput_createProject_input_projectTypeKey {
 
 "A predefined configuration for a project. The type of the \`projectTemplateKey\` must match with the type of the \`projectTypeKey\`."
 enum mutationInput_createProject_input_projectTemplateKey {
-  com_pyxis_greenhopper_jira_COLON_gh_simplified_agility_kanban
-  com_pyxis_greenhopper_jira_COLON_gh_simplified_agility_scrum
-  com_pyxis_greenhopper_jira_COLON_gh_simplified_basic
-  com_pyxis_greenhopper_jira_COLON_gh_simplified_kanban_classic
-  com_pyxis_greenhopper_jira_COLON_gh_simplified_scrum_classic
-  com_atlassian_servicedesk_COLON_simplified_it_service_management
-  com_atlassian_servicedesk_COLON_simplified_general_service_desk
-  com_atlassian_servicedesk_COLON_simplified_general_service_desk_it
-  com_atlassian_servicedesk_COLON_simplified_general_service_desk_business
-  com_atlassian_servicedesk_COLON_simplified_internal_service_desk
-  com_atlassian_servicedesk_COLON_simplified_external_service_desk
-  com_atlassian_servicedesk_COLON_simplified_hr_service_desk
-  com_atlassian_servicedesk_COLON_simplified_facilities_service_desk
-  com_atlassian_servicedesk_COLON_simplified_legal_service_desk
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_content_management
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_document_approval
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_lead_tracking
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_process_control
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_procurement
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_project_management
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_recruitment
-  com_atlassian_jira_core_project_templates_COLON_jira_core_simplified_task_
+  com_pyxis_greenhopper_jira_gh_simplified_agility_kanban
+  com_pyxis_greenhopper_jira_gh_simplified_agility_scrum
+  com_pyxis_greenhopper_jira_gh_simplified_basic
+  com_pyxis_greenhopper_jira_gh_simplified_kanban_classic
+  com_pyxis_greenhopper_jira_gh_simplified_scrum_classic
+  com_atlassian_servicedesk_simplified_it_service_management
+  com_atlassian_servicedesk_simplified_general_service_desk
+  com_atlassian_servicedesk_simplified_general_service_desk_it
+  com_atlassian_servicedesk_simplified_general_service_desk_business
+  com_atlassian_servicedesk_simplified_internal_service_desk
+  com_atlassian_servicedesk_simplified_external_service_desk
+  com_atlassian_servicedesk_simplified_hr_service_desk
+  com_atlassian_servicedesk_simplified_facilities_service_desk
+  com_atlassian_servicedesk_simplified_legal_service_desk
+  com_atlassian_jira_core_project_templates_jira_core_simplified_content_management
+  com_atlassian_jira_core_project_templates_jira_core_simplified_document_approval
+  com_atlassian_jira_core_project_templates_jira_core_simplified_lead_tracking
+  com_atlassian_jira_core_project_templates_jira_core_simplified_process_control
+  com_atlassian_jira_core_project_templates_jira_core_simplified_procurement
+  com_atlassian_jira_core_project_templates_jira_core_simplified_project_management
+  com_atlassian_jira_core_project_templates_jira_core_simplified_recruitment
+  com_atlassian_jira_core_project_templates_jira_core_simplified_task_
 }
 
 "Details about the project."
@@ -166965,9 +166965,9 @@ input WebhookDetails_Input {
 }
 
 enum mutationInput_registerDynamicWebhooks_input_webhooks_items_events_items {
-  jira_COLON_issue_created
-  jira_COLON_issue_updated
-  jira_COLON_issue_deleted
+  jira_issue_created
+  jira_issue_updated
+  jira_issue_deleted
   comment_created
   comment_updated
   comment_deleted

packages/utils/src/sanitize-name-for-graphql.ts

@@ -54,7 +54,7 @@ export function sanitizeNameForGraphQL(unsafeName: string): string {
     for (const ch of unsanitizedName) {
       if (/^[_a-zA-Z0-9]$/.test(ch)) {
         sanitizedName += ch;
-      } else if (ch === ' ' || ch === '-' || ch === '.' || ch === '/') {
+      } else if (ch === ' ' || ch === '-' || ch === '.' || ch === '/' || ch === ':') {
         sanitizedName += '_';
       } else {
         sanitizedName += `_${getKnownCharacterOrCharCode(ch)}_`;

website/src/pages/docs/handlers/openapi.mdx

@@ -52,7 +52,7 @@ We use `operationId` for the names, and aim to keep it as close as possible to o
 ### Type naming
 
 We adjust `operationId` only when necessary according to the GraphQL spec:
-    - Chars  ` ` (white space), `.`, `/` and `-` are replaced with `_` (underscore)
+    - Chars  ` ` (white space), `.`, `/`, `:` and `-` are replaced with `_` (underscore)
     - Other chars which are not latin/digits are replaced with their char codes
     - If first char of the name is a digit, we prefix it with `_` (GraphQL spec doesn’t allow that)