THREESCALE-3927 Update Swagger to Open API 3.0

app/controllers/api_docs/services_controller.rb

@@ -41,7 +41,7 @@ def initialize(name, system_name)
 
     def json
       parsed_content = JSON.parse(file_content)
-      parsed_content['basePath'] = backend_base_host if backend_api?
+      parsed_content['servers'] = [{ 'url' => backend_base_host }] if backend_api?
 
       parsed_content
     end
@@ -54,9 +54,9 @@ def file_path
 
     def file_name
       if onpremises_version? && onpremises_version_preferred?
-        "#{name} (on-premises)"
+        "#{system_name}_on_premises"
       else
-        name
+        system_name
       end
     end
 
@@ -115,18 +115,15 @@ def index
   def show
     system_name = params[:id].to_sym
     api_file = (api_files.fetch(system_name) { raise ActiveRecord::RecordNotFound }).dup
-    api_file['apis'] = exclude_forbidden_endpoints(api_file['apis'])
+    api_file['paths'] = exclude_forbidden_endpoints(api_file['paths']) if master_on_premises?
 
     render json: api_file
   end
 
   private
 
-  def exclude_forbidden_endpoints(apis)
-    apis.select do |api|
-      path = api['path']
-      !master_on_premises? || path.exclude?('plan')
-    end
+  def exclude_forbidden_endpoints(paths)
+    paths.select { |url| url.exclude?('plan') }
   end
 
   def allowed_api?(api)

app/javascript/packs/active_docs.ts

@@ -2,17 +2,17 @@
 import SwaggerUI from 'swagger-ui'
 import 'swagger-ui/dist/swagger-ui.css'
 
-import { autocompleteInterceptor } from 'ActiveDocs/OAS3Autocomplete'
+import { autocompleteRequestInterceptor } from 'ActiveDocs/OAS3Autocomplete'
 
 import 'ActiveDocs/swagger-ui-3-patch.scss'
 
 const accountDataUrl = '/api_docs/account_data.json'
 
 window.SwaggerUI = (args: SwaggerUI.SwaggerUIOptions, serviceEndpoint: string) => {
-  const responseInterceptor = (response: SwaggerUI.Response) => autocompleteInterceptor(response, accountDataUrl, serviceEndpoint, args.url)
+  const requestInterceptor = (request: SwaggerUI.Request) => autocompleteRequestInterceptor(request, accountDataUrl, serviceEndpoint)
 
   SwaggerUI({
     ...args,
-    responseInterceptor
+    requestInterceptor
   } as SwaggerUI.SwaggerUIOptions)
 }

app/javascript/packs/provider_active_docs.ts

@@ -0,0 +1,19 @@
+// We can define the 3scale plugins here and export the modified bundle
+import 'swagger-ui/dist/swagger-ui.css'
+
+import { renderApiDocs } from 'ActiveDocs/ThreeScaleApiDocs'
+
+import 'ActiveDocs/swagger-ui-3-provider-patch.scss'
+
+document.addEventListener('DOMContentLoaded', () => {
+  const containerId = 'api-containers'
+  const container = document.getElementById(containerId)
+
+  if (!container) {
+    throw new Error('The target ID was not found: ' + containerId)
+  }
+
+  const { baseUrl = '', apiDocsPath = '', apiDocsAccountDataPath = '' } = container.dataset
+
+  void renderApiDocs(container, apiDocsPath, baseUrl, apiDocsAccountDataPath)
+})

app/javascript/packs/service_active_docs.ts

@@ -1,7 +1,7 @@
 import SwaggerUI from 'swagger-ui'
 import 'swagger-ui/dist/swagger-ui.css'
 
-import { autocompleteInterceptor } from 'ActiveDocs/OAS3Autocomplete'
+import { autocompleteRequestInterceptor } from 'ActiveDocs/OAS3Autocomplete'
 
 import 'ActiveDocs/swagger-ui-3-provider-patch.scss'
 
@@ -16,12 +16,12 @@ document.addEventListener('DOMContentLoaded', () => {
   const { url = '', baseUrl = '', serviceEndpoint = '' } = container.dataset
   const accountDataUrl = `${baseUrl}${DATA_URL}`
 
-  const responseInterceptor: SwaggerUI.SwaggerUIOptions['responseInterceptor'] = (response) => autocompleteInterceptor(response, accountDataUrl, serviceEndpoint, url)
+  const requestInterceptor: SwaggerUI.SwaggerUIOptions['requestInterceptor'] = (request) => autocompleteRequestInterceptor(request, accountDataUrl, serviceEndpoint)
 
   SwaggerUI({
     url,
     // eslint-disable-next-line @typescript-eslint/naming-convention -- SwaggerUI API
     dom_id: `#${containerId}`,
-    responseInterceptor
+    requestInterceptor
   })
 })

app/javascript/src/ActiveDocs/OAS3Autocomplete.ts

@@ -13,15 +13,29 @@
 
 import { fetchData } from 'utilities/fetchData'
 
-import type { Response as SwaggerUIResponse } from 'swagger-ui'
+import type { Request as SwaggerUIRequest, Response as SwaggerUIResponse } from 'swagger-ui'
 import type { AccountData } from 'Types/SwaggerTypes'
 
 const X_DATA_ATTRIBUTE = 'x-data-threescale-name'
 
 const X_DATA_PARAMS_DESCRIPTIONS = {
-  user_keys: 'First user key from latest 5 applications',
+  metric_names: 'Latest 5 metrics',
+  metric_ids: 'Latest 5 metrics',
+  app_keys: 'First application key from the latest five applications',
   app_ids: 'Latest 5 applications (across all accounts and services)',
-  app_keys: 'First application key from the latest five applications'
+  application_ids: 'Latest 5 applications',
+  user_keys: 'First user key from latest 5 applications',
+  account_ids: 'Latest 5 accounts',
+  access_token: 'Access Token',
+  user_ids: 'First user (admin) of the latest 5 account',
+  service_ids: 'Service IDs',
+  service_tokens: 'Service tokens',
+  admin_ids: 'Latest 5 users (admin) from your account',
+  service_plan_ids: 'Latest 5 service plans',
+  application_plan_ids: 'Latest 5 application plans',
+  account_plan_ids: 'Latest 5 account plans',
+  client_ids: 'Client IDs from the latest five applications',
+  client_secrets: 'Client secrets from the latest five applications'
 } as const
 
 const addAutocompleteToParam = (param: any, accountData: AccountData): any => {
@@ -34,7 +48,7 @@ const addAutocompleteToParam = (param: any, accountData: AccountData): any => {
     ? {
       ...param,
       examples: autocompleteData.reduce<{ summary: string; value: string }[]>((examples, item) => (
-        [...examples, { summary: item.name, value: item.value }]
+        [...examples, { summary: item.value ? `${item.name} - ${item.value}` : item.name, value: item.value }]
       ), [{ summary: X_DATA_PARAMS_DESCRIPTIONS[xDataKey], value: '-' }])
     }
     : param
@@ -100,7 +114,7 @@ export interface Response extends SwaggerUIResponse {
   text: string;
 }
 
-const autocompleteOAS3 = async (response: SwaggerUIResponse, accountDataUrl: string, serviceEndpoint: string): Promise<Response> => {
+export const autocompleteOAS3 = async (response: SwaggerUIResponse, accountDataUrl: string, serviceEndpoint: string): Promise<Response> => {
   const bodyWithServer = injectServerToResponseBody(response.body, serviceEndpoint)
   const data = await fetchData<{ results: AccountData }>(accountDataUrl)
 
@@ -123,17 +137,16 @@ const autocompleteOAS3 = async (response: SwaggerUIResponse, accountDataUrl: str
 }
 
 /**
- * Intercept and process the response made by Swagger UI
- * Apply transformations (inject servers list and autocomplete data) to the response for OpenAPI spec requests, and
+ * Intercept the request, and if it fetches the OpenAPI specification, apply a custom responseInterceptor that applies
+ * transformations (inject servers list and autocomplete data) to the response
  * keep the responses to the actual API calls (made through 'Try it out') untouched
- * @param response response to the request made through Swagger UI
- * @param specUrl URL of the OpenAPI specification
+ * @param request request made through Swagger UI
  * @param accountDataUrl URL of the data for autocompletion
  * @param serviceEndpoint Public Base URL of the gateway, that will replace the  URL in the "servers" object
  */
-export const autocompleteInterceptor = (response: SwaggerUIResponse, accountDataUrl: string, serviceEndpoint: string, specUrl?: string): Promise<Response> | SwaggerUIResponse => {
-  if (!response.url.includes(specUrl)) {
-    return response
+export const autocompleteRequestInterceptor = (request: SwaggerUIRequest, accountDataUrl: string, serviceEndpoint: string): Promise<SwaggerUIRequest> | SwaggerUIRequest => {
+  if (request.loadSpec) {
+    request.responseInterceptor = (response: SwaggerUIResponse) => autocompleteOAS3(response, accountDataUrl, serviceEndpoint)
   }
-  return autocompleteOAS3(response, accountDataUrl, serviceEndpoint)
+  return request
 }

app/javascript/src/ActiveDocs/ThreeScaleApiDocs.ts

@@ -0,0 +1,138 @@
+import SwaggerUI from 'swagger-ui'
+// this is how SwaggerUI imports this function https://github.com/swagger-api/swagger-ui/pull/6208
+import { execute } from 'swagger-client/es/execute'
+
+import { fetchData } from 'utilities/fetchData'
+import { safeFromJsonString } from 'utilities/json-utils'
+import { autocompleteRequestInterceptor } from 'ActiveDocs/OAS3Autocomplete'
+
+import type { ApiDocsServices, BackendApiReportBody, BackendApiTransaction, BodyValue, BodyValueObject, FormData } from 'Types/SwaggerTypes'
+import type { ExecuteData } from 'swagger-client/es/execute'
+import type { SwaggerUIPlugin } from 'swagger-ui'
+
+const getApiSpecUrl = (baseUrl: string, specPath: string): string => {
+  return `${baseUrl.replace(/\/$/, '')}${specPath}`
+}
+
+const appendSwaggerDiv = (container: HTMLElement, id: string): void => {
+  const div = document.createElement('div')
+  div.setAttribute('class',  'api-docs-wrap')
+  div.setAttribute('id', id)
+
+  container.appendChild(div)
+}
+
+/**
+ * A recursive function that traverses the tree of the multi-level object `data`
+ * and for every leaf (i.e. value of primitive type) adds the value to `formData` single-level object,
+ * with the key that is the `path` to that leaf, e.g. 'paramName[nestedArray][0][arrayProp]'
+ * @param formData single-level object used as accumulator
+ * @param data current node of the object
+ * @param parentKey part of the formData key inherited from the upper level
+ */
+const buildFormData = (formData: FormData, data: BodyValue, parentKey?: string) => {
+  if (data && typeof data === 'object') {
+    const dataObject = data as BodyValueObject
+    Object.keys(dataObject).forEach((key: string) => {
+      buildFormData(formData, dataObject[key], parentKey ? `${parentKey}[${key}]` : key)
+    })
+  } else {
+    if (parentKey) {
+      formData[parentKey] = data ? data : ''
+    }
+  }
+}
+
+/**
+ * Transforms an object into form data representation. Does not URL-encode, because it will be done by
+ * swagger-client itself
+ * Returns an empty object if the argument is not an object
+ * Example:
+ * {
+ *   a_string: 'hello',
+ *   an_array: [
+ *     { first: 1 },
+ *     { second: 1, extra_param: 'with whitespace'}
+ *   ]
+ * }
+ * =>
+ * {
+ *   a_string: 'hello',
+ *   'an_array[0][first]': '1',
+ *   'an_array[1][second]': '1',
+ *   'an_array[1][extra_param]': 'with whitespace'
+ * }
+ * @param object
+ */
+export const objectToFormData = (object: BodyValueObject): FormData => {
+  if (typeof object !== 'object' || Array.isArray(object)) {
+    return {}
+  }
+  const formData: FormData = {}
+  buildFormData(formData, object)
+  return formData
+}
+
+/**
+ * Transforms the request body of the Service Management API Report, as
+ * SwaggerUI (or rather swagger-js) does not serialize arrays of objects properly
+ * The hack is to process the request body in two steps:
+ * 1. normalize the 'transactions' array, as its elements may be either an object (if the value is taken
+ *    from the example in the spec), or as a serialized JSON (if the field is changed manually)
+ * 2. "flatten" the objects by transforming them into form-data structure with the entries like
+ *    'transactions[0][app_id]': 'example'
+ *    'transactions[0][usage][hits]': 1
+ * @param body BackendApiReportBody
+ */
+export const transformReportRequestBody = (body: BackendApiReportBody): FormData => {
+  if (Array.isArray(body.transactions)) {
+    body.transactions = body.transactions.reduce((acc: BackendApiTransaction[], transaction) => {
+      let value = undefined
+      if (typeof transaction === 'object') {
+        value = transaction
+      } else {
+        value = safeFromJsonString<BackendApiTransaction>(transaction)
+      }
+      if (value) {
+        acc.push(value)
+      }
+      return acc
+    }, [])
+  }
+  return objectToFormData(body)
+}
+
+const RequestBodyTransformerPlugin: SwaggerUIPlugin = () => {
+  return {
+    fn: {
+      execute: (req: ExecuteData): unknown => {
+        if (req.contextUrl.includes('api_docs/services/service_management_api.json')
+            && req.operationId === 'report'
+            && req.requestBody) {
+          req.requestBody = transformReportRequestBody(req.requestBody as BackendApiReportBody)
+        }
+
+        return execute(req)
+      }
+    }
+  }
+}
+
+export const renderApiDocs = async (container: HTMLElement, apiDocsPath: string, baseUrl: string, apiDocsAccountDataPath: string): Promise<void> => {
+  const apiSpecs: ApiDocsServices = await fetchData<ApiDocsServices>(apiDocsPath)
+  apiSpecs.apis.forEach( api => {
+    const domId = api.system_name.replace(/_/g, '-')
+    const url = getApiSpecUrl(baseUrl, api.path)
+    appendSwaggerDiv(container, domId)
+    SwaggerUI({
+      url,
+      // eslint-disable-next-line @typescript-eslint/naming-convention -- Swagger UI
+      dom_id: `#${domId}`,
+      requestInterceptor: (request) => autocompleteRequestInterceptor(request, apiDocsAccountDataPath, ''),
+      tryItOutEnabled: true,
+      plugins: [
+        RequestBodyTransformerPlugin
+      ]
+    })
+  })
+}

app/javascript/src/Types/SwaggerTypes.ts

@@ -1,4 +1,46 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+
 export type AccountData = Record<string, {
   name: string;
   value: string;
 }[]>
+
+export interface ApiDocsService {
+  name: string;
+  system_name: string;
+  description: string;
+  path: string;
+  service_endpoint: string;
+}
+
+export interface ApiDocsServices {
+  host: string;
+  apis: ApiDocsService[];
+}
+
+export interface BackendApiTransaction extends BodyValueObject {
+  app_id?: string;
+  user_key?: string;
+  timestamp?: string;
+  usage: Record<string, number>;
+  log?: {
+    request?: string;
+    response?: string;
+    code?: string;
+  };
+}
+
+export interface BackendApiReportBody extends BodyValueObject {
+  service_token?: string;
+  service_id?: string;
+  transactions?: (BackendApiTransaction | string)[];
+}
+
+/**
+ * when using Record notation, the following error is thrown:
+ * 'TS2456: Type alias 'BodyValue' circularly references itself.'
+ */
+export type BodyValue = BodyValue[] | boolean | number | string | { [key: string]: BodyValue } | null | undefined
+export type BodyValueObject = Record<string, BodyValue>
+
+export type FormData = Record<string, boolean | number | string>

app/javascript/src/Types/swagger.d.ts

@@ -0,0 +1,27 @@
+// There are no official types for swagger-client. These has been inspired by:
+// - https://github.com/swagger-api/swagger-js/blob/master/src/execute/index.js
+declare module 'swagger-client/es/execute' {
+  import type { Request, Response, SupportedHTTPMethods } from 'swagger-ui'
+
+  export interface ExecuteData {
+    contextUrl: string;
+    fetch: (arg: unknown) => unknown;
+    method: SupportedHTTPMethods;
+    operation: unknown;
+    operationId: string;
+    parameters: unknown;
+    pathName: string;
+    requestBody?: unknown;
+    requestContentType: string;
+    requestInterceptor?: ((request: Request) => Promise<Request> | Request) | undefined;
+    responseContentType: string;
+    responseInterceptor?: ((response: Response) => Promise<Response> | Response) | undefined;
+    scheme: string;
+    securities: unknown;
+    server: string;
+    serverVariables: unknown;
+    spec: unknown;
+  }
+  function execute (req: ExecuteData): unknown
+  export { execute }
+}