feat: OpenAPI 3.1 support (#8367)

- New top-level field - `webhooks`. This allows describing out-of-band webhooks that are available as part of the API.

- New top-level field - `jsonSchemaDialect`. This allows defining of a default `$schema` value for Schema Objects

- The Info Object has a new `summary` field.

- The License Object now has a new `identifier` field for SPDX licenses. This `identifier` field is mutually exclusive with the `url` field. Either can be used in OpenAPI 3.1 definitions.

- Components Object now has a new entry `pathItems`, to allow for reusable Path Item Objects to be defined within a valid OpenAPI document.

- `License` and `Contact` components are now exported and available via `getComponent`

- New version predicates and selectors for `isOpenAPI30` and `isOpenAPI31`. This avoids needing to change the usage of `isOAS3` selector.

- New OAS3 components: `Webhooks`

- New OAS3 wrapped components: `Info`, `License`

src/core/components/info.jsx

@@ -23,7 +23,7 @@ export class InfoBasePath extends React.Component {
 }
 
 
-class Contact extends React.Component {
+export class Contact extends React.Component {
   static propTypes = {
     data: PropTypes.object,
     getComponent: PropTypes.func.isRequired,
@@ -53,7 +53,7 @@ class Contact extends React.Component {
   }
 }
 
-class License extends React.Component {
+export class License extends React.Component {
   static propTypes = {
     license: PropTypes.object,
     getComponent: PropTypes.func.isRequired,
@@ -64,7 +64,6 @@ class License extends React.Component {
 
   render(){
     let { license, getComponent, selectedServer, url: specUrl } = this.props
-
     const Link = getComponent("Link")
     let name = license.get("name") || "License"
     let url = safeBuildUrl(license.get("url"), specUrl, {selectedServer})
@@ -125,6 +124,7 @@ export default class Info extends React.Component {
     const VersionStamp = getComponent("VersionStamp")
     const InfoUrl = getComponent("InfoUrl")
     const InfoBasePath = getComponent("InfoBasePath")
+    const License = getComponent("License")
 
     return (
       <div className="info">

src/core/components/layouts/base.jsx

@@ -20,6 +20,7 @@ export default class BaseLayout extends React.Component {
     let VersionPragmaFilter = getComponent("VersionPragmaFilter")
     let Operations = getComponent("operations", true)
     let Models = getComponent("Models", true)
+    let Webhooks = getComponent("Webhooks", true)
     let Row = getComponent("Row")
     let Col = getComponent("Col")
     let Errors = getComponent("errors", true)
@@ -30,6 +31,7 @@ export default class BaseLayout extends React.Component {
     const FilterContainer = getComponent("FilterContainer", true)
     let isSwagger2 = specSelectors.isSwagger2()
     let isOAS3 = specSelectors.isOAS3()
+    const isOpenAPI31 = specSelectors.selectIsOpenAPI31()
 
     const isSpecEmpty = !specSelectors.specStr()
 
@@ -112,6 +114,13 @@ export default class BaseLayout extends React.Component {
               <Operations/>
             </Col>
           </Row>
+          { isOpenAPI31 &&
+            <Row className="webhooks-container">
+              <Col mobile={12} desktop={12} >
+                <Webhooks />
+              </Col>
+            </Row>
+          }
           <Row>
             <Col mobile={12} desktop={12} >
               <Models/>

src/core/plugins/oas3/components/index.js

@@ -6,6 +6,7 @@ import ServersContainer from "./servers-container"
 import RequestBodyEditor from "./request-body-editor"
 import HttpAuth from "./http-auth"
 import OperationServers from "./operation-servers"
+import Webhooks from "./webhooks"
 
 export default {
   Callbacks,
@@ -15,5 +16,6 @@ export default {
   ServersContainer,
   RequestBodyEditor,
   OperationServers,
-  operationLink: OperationLink
+  operationLink: OperationLink,
+  Webhooks
 }

src/core/plugins/oas3/components/request-body.jsx

@@ -6,13 +6,13 @@ import { getCommonExtensions, getSampleSchema, stringify, isEmptyValue } from "c
 import { getKnownSyntaxHighlighterLanguage } from "core/utils/jsonParse"
 
 export const getDefaultRequestBodyValue = (requestBody, mediaType, activeExamplesKey) => {
-  const mediaTypeValue = requestBody.getIn(["content", mediaType])
-  const schema = mediaTypeValue.get("schema").toJS()
+  const mediaTypeValue = requestBody?.getIn(["content", mediaType])
+  const schema = mediaTypeValue?.get("schema").toJS()
 
-  const hasExamplesKey = mediaTypeValue.get("examples") !== undefined
-  const exampleSchema = mediaTypeValue.get("example")
+  const hasExamplesKey = mediaTypeValue?.get("examples") !== undefined
+  const exampleSchema = mediaTypeValue?.get("example")
   const mediaTypeExample = hasExamplesKey
-    ? mediaTypeValue.getIn([
+    ? mediaTypeValue?.getIn([
       "examples",
       activeExamplesKey,
       "value"

src/core/plugins/oas3/components/webhooks.jsx

@@ -0,0 +1,60 @@
+// OpenAPI 3.1 feature
+import React from "react"
+import PropTypes from "prop-types"
+import { fromJS } from "immutable"
+import ImPropTypes from "react-immutable-proptypes"
+
+// Todo: nice to have: similar to operation-tags, could have an expand/collapse button
+// to show/hide all webhook items
+const Webhooks = (props) => {
+  const { specSelectors, getComponent, specPath } = props
+  
+  const webhooksPathItems = specSelectors.selectWebhooks() // OrderedMap
+  if (!webhooksPathItems || webhooksPathItems?.size < 1) {
+    return null
+  }
+  const OperationContainer = getComponent("OperationContainer", true)
+
+  const pathItemsElements = webhooksPathItems.entrySeq().map(([pathItemName, pathItem], i) => {
+    const operationsElements = pathItem.entrySeq().map(([operationMethod, operation], j) => {
+      const op = fromJS({
+        operation
+      })
+      // using defaultProps for `specPath`; may want to remove from props
+      // and/or if extract to separate PathItem component, allow for use 
+      // with both OAS3.1 "webhooks" and "components.pathItems" features
+      return <OperationContainer
+        {...props}
+        op={op}
+        key={`${pathItemName}--${operationMethod}--${j}`}
+        tag={""}
+        method={operationMethod}
+        path={pathItemName}
+        specPath={specPath.push("webhooks", pathItemName, operationMethod)}
+        allowTryItOut={false}
+      />
+    })
+    return <div key={`${pathItemName}-${i}`}>
+      {operationsElements}
+    </div>
+  })
+
+  return (
+    <div className="webhooks">
+      <h2>Webhooks</h2>
+      {pathItemsElements}
+    </div>
+  )
+}
+
+Webhooks.propTypes = {
+  specSelectors: PropTypes.object.isRequired,
+  getComponent: PropTypes.func.isRequired,
+  specPath: ImPropTypes.list,
+}
+
+Webhooks.defaultProps = {
+  specPath: fromJS([])
+}
+
+export default Webhooks

src/core/plugins/oas3/helpers.jsx

@@ -1,16 +1,27 @@
 import React from "react"
 
+export function isOpenAPI30(jsSpec) {
+  const oasVersion = jsSpec.get("openapi")
+  if (typeof oasVersion !== "string") {
+    return false
+  }
+  return oasVersion.startsWith("3.0.") && oasVersion.length > 4
+}
+
+export function isOpenAPI31(jsSpec) {
+  const oasVersion = jsSpec.get("openapi")
+  if (typeof oasVersion !== "string") {
+    return false
+  }
+  return oasVersion.startsWith("3.1.") && oasVersion.length > 4
+}
+
 export function isOAS3(jsSpec) {
   const oasVersion = jsSpec.get("openapi")
   if(typeof oasVersion !== "string") {
     return false
   }
-
-  // we gate against `3.1` because we want to explicitly opt into supporting it
-  // at some point in the future -- KS, 7/2018
-
-  // starts with, but is not `3.0.` exactly
-  return oasVersion.startsWith("3.0.") && oasVersion.length > 4
+  return isOpenAPI30(jsSpec) || isOpenAPI31(jsSpec)
 }
 
 export function isSwagger2(jsSpec) {

src/core/plugins/oas3/spec-extensions/selectors.js

@@ -1,10 +1,11 @@
 import { createSelector } from "reselect"
 import { Map } from "immutable"
-import { isOAS3 as isOAS3Helper, isSwagger2 as isSwagger2Helper } from "../helpers"
+import { isOAS3 as isOAS3Helper, isOpenAPI31 as isOpenAPI31Helper, isSwagger2 as isSwagger2Helper } from "../helpers"
 
 
 // Helpers
 
+// 1/2023: as of now, more accurately, isAnyOAS3
 function onlyOAS3(selector) {
   return () => (system, ...args) => {
     const spec = system.getSystem().specSelectors.specJson()
@@ -16,6 +17,17 @@ function onlyOAS3(selector) {
   }
 }
 
+function isOpenAPI31(selector) {
+  return () => (system, ...args) => {
+    const spec = system.getSystem().specSelectors.specJson()
+    if (isOpenAPI31Helper(spec)) {
+      return selector(...args)
+    } else {
+      return null
+    }
+  }
+}
+
 const state = state => {
   return state || Map()
 }
@@ -48,3 +60,13 @@ export const isSwagger2 = (ori, system) => () => {
   const spec = system.getSystem().specSelectors.specJson()
   return isSwagger2Helper(spec)
 }
+
+export const selectIsOpenAPI31 = (ori, system) => () => {
+  const spec = system.getSystem().specSelectors.specJson()
+  return isOpenAPI31Helper(spec)
+}
+
+export const selectWebhooks = isOpenAPI31(createSelector(
+  spec,
+  spec => spec.getIn(["webhooks"]) || Map()
+))

src/core/plugins/oas3/spec-extensions/wrap-selectors.js

@@ -1,11 +1,11 @@
 import { createSelector } from "reselect"
 import { specJsonWithResolvedSubtrees } from "../../spec/selectors"
 import { Map } from "immutable"
-import { isOAS3 as isOAS3Helper, isSwagger2 as isSwagger2Helper } from "../helpers"
+import { isOAS3 as isOAS3Helper, isOpenAPI31 as isOpenAPI31Helper, isSwagger2 as isSwagger2Helper } from "../helpers"
 
 
 // Helpers
-
+// 1/2023: as of now, more accurately, isAnyOAS3
 function onlyOAS3(selector) {
   return (ori, system) => (...args) => {
     const spec = system.getSystem().specSelectors.specJson()
@@ -17,6 +17,17 @@ function onlyOAS3(selector) {
   }
 }
 
+function isOpenAPI31(selector) {
+  return (ori, system) => (...args) => {
+    const spec = system.getSystem().specSelectors.specJson()
+    if (isOpenAPI31Helper(spec)) {
+      return selector(...args)
+    } else {
+      return null
+    }
+  }
+}
+
 const state = state => {
   return state || Map()
 }
@@ -83,3 +94,14 @@ export const isSwagger2 = (ori, system) => () => {
   const spec = system.getSystem().specSelectors.specJson()
   return isSwagger2Helper(Map.isMap(spec) ? spec : Map())
 }
+
+export const selectIsOpenAPI31 = (ori, system) => () => {
+  const spec = system.getSystem().specSelectors.specJson()
+  return isOpenAPI31Helper(Map.isMap(spec) ? spec : Map())
+}
+
+export const selectWebhooks = isOpenAPI31(createSelector(
+  spec,
+  spec => spec.getIn(["webhooks"]) || Map()
+))
+

src/core/plugins/oas3/wrap-components/index.js

@@ -4,6 +4,8 @@ import VersionStamp from "./version-stamp"
 import OnlineValidatorBadge from "./online-validator-badge"
 import Model from "./model"
 import JsonSchema_string from "./json-schema-string"
+import License from "./license"
+import info from "./info"
 
 export default {
   Markdown,
@@ -12,4 +14,6 @@ export default {
   VersionStamp,
   model: Model,
   onlineValidatorBadge: OnlineValidatorBadge,
+  License,
+  info,
 }

src/core/plugins/oas3/wrap-components/info.jsx

@@ -0,0 +1,78 @@
+import React from "react"
+import PropTypes from "prop-types"
+import ImPropTypes from "react-immutable-proptypes"
+import { sanitizeUrl } from "core/utils"
+import { safeBuildUrl } from "core/utils/url"
+import { OAS3ComponentWrapFactory } from "../helpers"
+
+const Info = (props) => {
+  const { info, url, host, basePath, getComponent, specSelectors, externalDocs, selectedServer, url: specUrl } = props
+  const isOpenAPI31 = specSelectors.selectIsOpenAPI31()
+  const version = info.get("version")
+  const description = info.get("description")
+  const title = info.get("title")
+  const termsOfServiceUrl = safeBuildUrl(info.get("termsOfService"), specUrl, { selectedServer })
+  const contact = info.get("contact")
+  const license = info.get("license")
+  // note that ux may want to move summary to a sub-heading, as summary is a string that does not need to be Markdown
+  const summary = info.get("summary") // OAS3.1 field
+  const rawExternalDocsUrl = externalDocs && externalDocs.get("url")
+  const externalDocsUrl = safeBuildUrl(rawExternalDocsUrl, specUrl, { selectedServer })
+  const externalDocsDescription = externalDocs && externalDocs.get("description")
+
+  const Markdown = getComponent("Markdown", true)
+  const Link = getComponent("Link")
+  const VersionStamp = getComponent("VersionStamp")
+  const InfoUrl = getComponent("InfoUrl")
+  const InfoBasePath = getComponent("InfoBasePath")
+  const License = getComponent("License")
+  const Contact = getComponent("Contact")
+
+  return (
+    <div className="info">
+      <hgroup className="main">
+        <h2 className="title" >{title}
+          {version && <VersionStamp version={version}></VersionStamp>}
+        </h2>
+        {host || basePath ? <InfoBasePath host={host} basePath={basePath} /> : null}
+        {url && <InfoUrl getComponent={getComponent} url={url} />}
+      </hgroup>
+
+      {
+        isOpenAPI31 && summary && <div className="info__summary">
+          <Markdown source={summary} />
+        </div>
+      }
+      <div className="description">
+        <Markdown source={description} />
+      </div>
+
+      {
+        termsOfServiceUrl && <div className="info__tos">
+          <Link target="_blank" href={sanitizeUrl(termsOfServiceUrl)}>Terms of service</Link>
+        </div>
+      }
+
+      {contact && contact.size ? <Contact getComponent={getComponent} data={contact} selectedServer={selectedServer} url={url} /> : null}
+      {license && license.size ? <License getComponent={getComponent} license={license} selectedServer={selectedServer} url={url} /> : null}
+      {externalDocsUrl ?
+        <Link className="info__extdocs" target="_blank" href={sanitizeUrl(externalDocsUrl)}>{externalDocsDescription || externalDocsUrl}</Link>
+        : null}
+
+    </div>
+  )
+}
+
+Info.propTypes = {
+  info: PropTypes.object,
+  url: PropTypes.string,
+  host: PropTypes.string,
+  basePath: PropTypes.string,
+  externalDocs: ImPropTypes.map,
+  getComponent: PropTypes.func.isRequired,
+  specSelectors: PropTypes.object.isRequired,
+  oas3selectors: PropTypes.func,
+  selectedServer: PropTypes.string,
+}
+
+export default OAS3ComponentWrapFactory(Info)

src/core/plugins/oas3/wrap-components/license.jsx

@@ -0,0 +1,49 @@
+import React from "react"
+import PropTypes from "prop-types"
+import { sanitizeUrl } from "core/utils"
+import { safeBuildUrl } from "core/utils/url"
+import { OAS3ComponentWrapFactory } from "../helpers"
+
+const baseSPDXurl = "https://spdx.org/licenses"
+const createSPDXurl = (identifier) => {
+  return `${baseSPDXurl}/${identifier}.html`
+}
+
+const License = (props) => {
+  const { license, getComponent, selectedServer, url: specUrl, specSelectors } = props
+  const Link = getComponent("Link")
+  const name = license.get("name") || "License"
+  const url = safeBuildUrl(license.get("url"), specUrl, { selectedServer })
+  const identifier = license.get("identifier") || "" // OAS3.1 field
+  const identifierUrl = createSPDXurl(identifier)
+  const isOpenAPI31 = specSelectors.selectIsOpenAPI31()
+
+  return (
+    <div className="info__license">
+      {
+        !isOpenAPI31 && url && <div className="info__license__url"><Link target="_blank" href={sanitizeUrl(url)}>{name}</Link></div>
+      }
+      {
+        isOpenAPI31 && url && !identifier && <div className="info__license__url"><Link target="_blank" href={sanitizeUrl(url)}>{name}</Link></div>
+      }
+      {
+        isOpenAPI31 && identifier && !url && <div className="info__license__identifier"><Link target="_blank" href={sanitizeUrl(baseSPDXurl)}>SPDX License</Link>: <Link target="_blank" href={sanitizeUrl(identifierUrl)}>{identifier}</Link></div>
+      }
+      {/* {
+        isOpenAPI31 && identifier && url && <div className="info__license_error">Render Error: License.url and License.identifier are mutually exclusive fields</div>
+      } */}
+    </div>
+  )
+}
+
+License.propTypes = {
+  license: PropTypes.shape({
+    get: PropTypes.func,
+  }),
+  getComponent: PropTypes.func.isRequired,
+  specSelectors: PropTypes.object.isRequired,
+  selectedServer: PropTypes.string,
+  url: PropTypes.string.isRequired,
+}
+
+export default OAS3ComponentWrapFactory(License)

src/core/presets/base.js

@@ -59,7 +59,9 @@ import Overview from "core/components/overview"
 import InitializedInput from "core/components/initialized-input"
 import Info, {
   InfoUrl,
-  InfoBasePath
+  InfoBasePath,
+  License,
+  Contact,
 } from "core/components/info"
 import InfoContainer from "core/containers/info"
 import JumpToPath from "core/components/jump-to-path"
@@ -163,6 +165,8 @@ export default function() {
       DeepLink,
       InfoUrl,
       InfoBasePath,
+      License,
+      Contact,
       SvgAssets,
       Example,
       ExamplesSelect,