Merge pull request #1127 from swagger-api/ft/oas3-tio

OAS3: Try-It-Out

Author: shockey

examples/oas3.js

@@ -0,0 +1,2 @@
+// TODO: OAS3: provide examples
+// requestBody, etc

src/execute.js

@@ -5,7 +5,7 @@ import isArray from 'lodash/isArray'
 import btoa from 'btoa'
 import url from 'url'
 import http, {mergeInQueryOrForm} from './http'
-import {getOperationRaw, idFromPathMethod, legacyIdFromPathMethod} from './helpers'
+import {getOperationRaw, idFromPathMethod, legacyIdFromPathMethod, isOAS3} from './helpers'
 import createError from './specmap/lib/create-error'
 
 const arrayOrEmpty = (ar) => {
@@ -24,6 +24,8 @@ export const self = {
 
 // These functions will update the request.
 // They'll be given {req, value, paramter, spec, operation}.
+
+
 export const PARAMETER_BUILDERS = {
   body: bodyBuilder,
   header: headerBuilder,
@@ -66,13 +68,16 @@ export function execute({
 export function buildRequest({
   spec, operationId, parameters, securities, requestContentType,
   responseContentType, parameterBuilders, scheme,
-  requestInterceptor, responseInterceptor, contextUrl, userFetch
+  requestInterceptor, responseInterceptor, contextUrl, userFetch,
+  requestBody, server, serverVariables
 }) {
+  const specIsOAS3 = isOAS3(spec)
+
   parameterBuilders = parameterBuilders || PARAMETER_BUILDERS
 
   // Base Template
   let req = {
-    url: baseUrl({spec, scheme, contextUrl}),
+    url: baseUrl({spec, scheme, contextUrl, server, serverVariables}),
     credentials: 'same-origin',
     headers: {
       // This breaks CORSs... removing this line... probably breaks oAuth. Need to address that
@@ -120,6 +125,9 @@ export function buildRequest({
       const builder = parameterBuilders[parameter.in]
       let value
 
+      // REVIEW: OAS3: have any key names or parameter shapes changed?
+      // Any new features that need to be plugged in here?
+
       if (parameter.in === 'body' && parameter.schema && parameter.schema.properties) {
         value = parameters
       }
@@ -135,28 +143,82 @@ export function buildRequest({
       }
 
       if (builder) {
-        builder({req, parameter, value, operation, spec})
+        builder({req, parameter, value, operation, spec, specIsOAS3})
       }
     })
 
+  const requestBodyDef = operation.requestBody || {}
+  const requestBodyMediaTypes = Object.keys(requestBodyDef.content || {})
+
+  // for OAS3: set the Content-Type
+  if (specIsOAS3 && requestBody) {
+    // does the passed requestContentType appear in the requestBody definition?
+    const isExplicitContentTypeValid = requestContentType
+      && requestBodyMediaTypes.indexOf(requestContentType) > -1
+
+    if (requestContentType && isExplicitContentTypeValid) {
+      req.headers['Content-Type'] = requestContentType
+    }
+    else if (!requestContentType) {
+      const firstMediaType = requestBodyMediaTypes[0]
+      if (firstMediaType) {
+        req.headers['Content-Type'] = firstMediaType
+        requestContentType = firstMediaType
+      }
+    }
+  }
+
+  // for OAS3: add requestBody to request
+  if (specIsOAS3 && requestBody) {
+    if (requestContentType) {
+      if (requestBodyMediaTypes.indexOf(requestContentType) > -1) {
+        // only attach body if the requestBody has a definition for the
+        // contentType that has been explicitly set
+        if (requestContentType === 'application/x-www-form-urlencoded') {
+          if (typeof requestBody === 'object') {
+            req.form = {}
+            Object.keys(requestBody).forEach((k) => {
+              const val = requestBody[k]
+              req.form[k] = {
+                value: val
+              }
+            })
+          }
+          else {
+            req.form = requestBody
+          }
+        }
+        else {
+          req.body = requestBody
+        }
+      }
+    }
+    else {
+      req.body = requestBody
+    }
+  }
+
+
   // Add securities, which are applicable
+  // REVIEW: OAS3: what changed in securities?
   req = applySecurities({request: req, securities, operation, spec})
 
-  if (req.body || req.form) {
+  if (!specIsOAS3 && (req.body || req.form)) {
+    // all following conditionals are Swagger2 only
     if (requestContentType) {
-      req.headers['content-type'] = requestContentType
+      req.headers['Content-Type'] = requestContentType
     }
     else if (Array.isArray(operation.consumes)) {
-      req.headers['content-type'] = operation.consumes[0]
+      req.headers['Content-Type'] = operation.consumes[0]
     }
     else if (Array.isArray(spec.consumes)) {
-      req.headers['content-type'] = spec.consumes[0]
+      req.headers['Content-Type'] = spec.consumes[0]
     }
-    else if (operation.parameters.filter(p => p.type === 'file').length) {
-      req.headers['content-type'] = 'multipart/form-data'
+    else if (operation.parameters && operation.parameters.filter(p => p.type === 'file').length) {
+      req.headers['Content-Type'] = 'multipart/form-data'
     }
-    else if (operation.parameters.filter(p => p.in === 'formData').length) {
-      req.headers['content-type'] = 'application/x-www-form-urlencoded'
+    else if (operation.parameters && operation.parameters.filter(p => p.in === 'formData').length) {
+      req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
     }
   }
 
@@ -168,12 +230,16 @@ export function buildRequest({
 }
 
 // Add the body to the request
-export function bodyBuilder({req, value}) {
+export function bodyBuilder({req, value, specIsOAS3}) {
+  if (specIsOAS3) {
+    return
+  }
   req.body = value
 }
 
 // Add a form data object.
 export function formDataBuilder({req, value, parameter}) {
+  // REVIEW: OAS3: check for any parameter changes that affect the builder
   req.form = req.form || {}
   if (value || parameter.allowEmptyValue) {
     req.form[parameter.name] = {
@@ -186,6 +252,7 @@ export function formDataBuilder({req, value, parameter}) {
 
 // Add a header to the request
 export function headerBuilder({req, parameter, value}) {
+  // REVIEW: OAS3: check for any parameter changes that affect the builder
   req.headers = req.headers || {}
   if (typeof value !== 'undefined') {
     req.headers[parameter.name] = value
@@ -194,11 +261,13 @@ export function headerBuilder({req, parameter, value}) {
 
 // Replace path paramters, with values ( ie: the URL )
 export function pathBuilder({req, value, parameter}) {
+  // REVIEW: OAS3: check for any parameter changes that affect the builder
   req.url = req.url.replace(`{${parameter.name}}`, encodeURIComponent(value))
 }
 
 // Add a query to the `query` object, which will later be stringified into the URL's search
 export function queryBuilder({req, value, parameter}) {
+  // REVIEW: OAS3: check for any parameter changes that affect the builder
   req.query = req.query || {}
 
   if (value === false && parameter.type === 'boolean') {
@@ -224,8 +293,69 @@ export function queryBuilder({req, value, parameter}) {
 
 const stripNonAlpha = str => (str ? str.replace(/\W/g, '') : null)
 
+export function baseUrl(obj) {
+  const specIsOAS3 = isOAS3(obj.spec)
+
+  return specIsOAS3 ? oas3BaseUrl(obj) : swagger2BaseUrl(obj)
+}
+
+function oas3BaseUrl({spec, server, serverVariables = {}}) {
+  const servers = spec.servers
+
+  let selectedServerUrl = ''
+  let selectedServerObj = null
+
+  if (!servers || !Array.isArray(servers)) {
+    return ''
+  }
+
+  if (server) {
+    const serverUrls = servers.map(srv => srv.url)
+
+    if (serverUrls.indexOf(server) > -1) {
+      selectedServerUrl = server
+      selectedServerObj = servers[serverUrls.indexOf(server)]
+    }
+  }
+
+  if (!selectedServerUrl) {
+    // default to the first server if we don't have one by now
+    selectedServerUrl = servers[0].url
+    selectedServerObj = servers[0]
+  }
+
+  if (selectedServerUrl.indexOf('{') > -1) {
+    // do variable substitution
+    const varNames = getVariableTemplateNames(selectedServerUrl)
+    varNames.forEach((vari) => {
+      if (selectedServerObj.variables && selectedServerObj.variables[vari]) {
+        // variable is defined in server
+        const variableDefinition = selectedServerObj.variables[vari]
+        const variableValue = serverVariables[vari] || variableDefinition.default
+
+        const re = new RegExp(`{${vari}}`, 'g')
+        selectedServerUrl = selectedServerUrl.replace(re, variableValue)
+      }
+    })
+  }
+
+  return selectedServerUrl
+}
+
+function getVariableTemplateNames(str) {
+  const results = []
+  const re = /{([^}]+)}/g
+  let text
+
+  // eslint-disable-next-line no-cond-assign
+  while (text = re.exec(str)) {
+    results.push(text[1])
+  }
+  return results
+}
+
 // Compose the baseUrl ( scheme + host + basePath )
-export function baseUrl({spec, scheme, contextUrl = ''}) {
+function swagger2BaseUrl({spec, scheme, contextUrl = ''}) {
   const parsedContextUrl = url.parse(contextUrl)
   const firstSchemeInSpec = Array.isArray(spec.schemes) ? spec.schemes[0] : null
 

src/helpers.js

@@ -5,6 +5,25 @@ const escapeString = (str) => {
   return str.replace(/[^\w]/gi, '_')
 }
 
+// Spec version detection
+export function isOAS3(spec) {
+  const oasVersion = spec.openapi
+  if (!oasVersion) {
+    return false
+  }
+
+  return oasVersion.startsWith('3.0.0')
+}
+
+export function isSwagger2(spec) {
+  const swaggerVersion = spec.swagger
+  if (!swaggerVersion) {
+    return false
+  }
+
+  return swaggerVersion.startsWith('2')
+}
+
 // Strategy for determining operationId
 export function opId(operation, pathName, method = '') {
   const idWithoutWhitespace = (operation.operationId || '').replace(/\s/g, '')
@@ -86,6 +105,9 @@ export function eachOperation(spec, cb, find) {
   }
 }
 
+// REVIEW: OAS3: identify normalization steps that need changes
+// ...maybe create `normalizeOAS3`?
+
 export function normalizeSwagger(parsedSpec) {
   const {spec} = parsedSpec
   const {paths} = spec

src/http.js

@@ -135,6 +135,7 @@ function isFile(obj) {
 }
 
 function formatValue({value, collectionFormat, allowEmptyValue}, skipEncoding) {
+  // REVIEW: OAS3: usage of this fn for compatibility w/ new value formats
   const SEPARATORS = {
     csv: ',',
     ssv: '%20',

src/index.js

@@ -81,6 +81,7 @@ Swagger.prototype = {
 Swagger.prototype.applyDefaults = function () {
   const spec = this.spec
   const specUrl = this.url
+  // TODO: OAS3: support servers here
   if (specUrl && specUrl.startsWith('http')) {
     const parsed = Url.parse(specUrl)
     if (!spec.host) {