feat: Render external docs links and descriptions (#7559)

Co-authored-by: Tim Lai <timothy.lai@smartbear.com>

src/core/components/array-model.jsx

@@ -1,6 +1,7 @@
 import React, { Component } from "react"
 import PropTypes from "prop-types"
 import ImPropTypes from "react-immutable-proptypes"
+import { sanitizeUrl } from "core/utils"
 
 const propClass = "property"
 
@@ -25,12 +26,16 @@ export default class ArrayModel extends Component {
     let description = schema.get("description")
     let items = schema.get("items")
     let title = schema.get("title") || displayName || name
-    let properties = schema.filter( ( v, key) => ["type", "items", "description", "$$ref"].indexOf(key) === -1 )
+    let properties = schema.filter( ( v, key) => ["type", "items", "description", "$$ref", "externalDocs"].indexOf(key) === -1 )
+    let externalDocsUrl = schema.getIn(["externalDocs", "url"])
+    let externalDocsDescription = schema.getIn(["externalDocs", "description"])
+
 
     const Markdown = getComponent("Markdown", true)
     const ModelCollapse = getComponent("ModelCollapse")
     const Model = getComponent("Model")
     const Property = getComponent("Property")
+    const Link = getComponent("Link")
 
     const titleEl = title &&
       <span className="model-title">
@@ -52,6 +57,11 @@ export default class ArrayModel extends Component {
             !description ? (properties.size ? <div className="markdown"></div> : null) :
               <Markdown source={ description } />
           }
+          { externalDocsUrl &&
+            <div className="external-docs">
+               <Link target="_blank" href={sanitizeUrl(externalDocsUrl)}>{externalDocsDescription || externalDocsUrl}</Link>
+             </div>
+          }
           <span>
             <Model
               { ...this.props }

src/core/components/object-model.jsx

@@ -2,6 +2,7 @@ import React, { Component, } from "react"
 import PropTypes from "prop-types"
 import { List } from "immutable"
 import ImPropTypes from "react-immutable-proptypes"
+import { sanitizeUrl } from "core/utils"
 
 const braceOpen = "{"
 const braceClose = "}"
@@ -44,12 +45,15 @@ export default class ObjectModel extends Component {
     let infoProperties = schema
       .filter( ( v, key) => ["maxProperties", "minProperties", "nullable", "example"].indexOf(key) !== -1 )
     let deprecated = schema.get("deprecated")
+    let externalDocsUrl = schema.getIn(["externalDocs", "url"])
+    let externalDocsDescription = schema.getIn(["externalDocs", "description"])
 
     const JumpToPath = getComponent("JumpToPath", true)
     const Markdown = getComponent("Markdown", true)
     const Model = getComponent("Model")
     const ModelCollapse = getComponent("ModelCollapse")
     const Property = getComponent("Property")
+    const Link = getComponent("Link")
 
     const JumpToPathSection = () => {
       return <span className="model-jump-to-path"><JumpToPath specPath={specPath} /></span>
@@ -93,6 +97,17 @@ export default class ObjectModel extends Component {
                     </td>
                   </tr>
               }
+              {
+                externalDocsUrl &&
+                <tr className={"external-docs"}>
+                  <td>
+                    externalDocs:
+                  </td>
+                  <td>
+                    <Link target="_blank" href={sanitizeUrl(externalDocsUrl)}>{externalDocsDescription || externalDocsUrl}</Link>
+                  </td>
+                </tr>
+              }
               {
                 !deprecated ? null :
                   <tr className={"property"}>
@@ -103,7 +118,6 @@ export default class ObjectModel extends Component {
                       true
                     </td>
                   </tr>
-
               }
               {
                 !(properties && properties.size) ? null : properties.entrySeq().filter(

src/core/components/operation-tag.jsx

@@ -88,18 +88,14 @@ export default class OperationTag extends React.Component {
             </small>
           }
 
-          {!tagExternalDocsDescription ? null :
+          {!tagExternalDocsUrl ? null :
             <div className="info__externaldocs">
               <small>
-                {tagExternalDocsDescription}
-                {tagExternalDocsUrl ? ": " : null}
-                {tagExternalDocsUrl ?
                 <Link
                     href={sanitizeUrl(tagExternalDocsUrl)}
                     onClick={(e) => e.stopPropagation()}
                     target="_blank"
-                  >{tagExternalDocsUrl}</Link> : null
+                  >{tagExternalDocsDescription || tagExternalDocsUrl}</Link>
-                }
               </small>
             </div>
           }

src/core/components/operation.jsx

@@ -133,9 +133,11 @@ export default class Operation extends PureComponent {
                 <div className="opblock-external-docs-wrapper">
                   <h4 className="opblock-title_normal">Find more details</h4>
                   <div className="opblock-external-docs">
+                    {externalDocs.description &&
                       <span className="opblock-external-docs__description">
                         <Markdown source={ externalDocs.description } />
                       </span> 
+                    }
                     <Link target="_blank" className="opblock-external-docs__link" href={sanitizeUrl(externalDocsUrl)}>{externalDocsUrl}</Link>
                   </div>
                 </div> : null

src/core/components/primitive-model.jsx

@@ -1,6 +1,6 @@
 import React, { Component } from "react"
 import PropTypes from "prop-types"
-import { getExtensions } from "core/utils"
+import { getExtensions, sanitizeUrl } from "core/utils"
 
 const propClass = "property primitive"
 
@@ -33,12 +33,17 @@ export default class Primitive extends Component {
     let description = schema.get("description")
     let extensions = getExtensions(schema)
     let properties = schema
-      .filter((_, key) => ["enum", "type", "format", "description", "$$ref"].indexOf(key) === -1)
+      .filter((_, key) => ["enum", "type", "format", "description", "$$ref", "externalDocs"].indexOf(key) === -1)
       .filterNot((_, key) => extensions.has(key))
+    let externalDocsUrl = schema.getIn(["externalDocs", "url"])
+    let externalDocsDescription = schema.getIn(["externalDocs", "description"])
+
     const Markdown = getComponent("Markdown", true)
     const EnumModel = getComponent("EnumModel")
     const Property = getComponent("Property")
     const ModelCollapse = getComponent("ModelCollapse")
+    const Link = getComponent("Link")
+
     const titleEl = title &&
       <span className="model-title">
         <span className="model-title__text">{title}</span>
@@ -60,6 +65,12 @@ export default class Primitive extends Component {
             !description ? null :
               <Markdown source={description} />
           }
+          {
+            externalDocsUrl &&
+            <div className="external-docs">
+               <Link target="_blank" href={sanitizeUrl(externalDocsUrl)}>{externalDocsDescription || externalDocsUrl}</Link>
+             </div>
+          }
           {
             xml && xml.size ? (<span><br /><span className={propClass}>xml:</span>
               {

src/style/_layout.scss

@@ -118,6 +118,11 @@
           flex: 1;
       }
     }
+
+    .info__externaldocs
+    {
+        text-align: right;
+    }
 }
 
 .parameter__type

src/style/_models.scss

@@ -108,6 +108,12 @@
              color: #6b6b6b;
         }
     }
+
+    .external-docs
+     {
+         color: #666;
+         font-weight: normal;
+     }
 }
 
 table.model
@@ -157,6 +163,19 @@ table.model
                 vertical-align: top;
             }
         }
+
+        &.external-docs
+        {
+            td:first-child
+            {
+                font-weight: bold;
+            }
+        }
+
+        .renderedMarkdown p:first-child
+        {
+            margin-top: 0;
+        }        
     }
 }
 

test/e2e-cypress/static/documents/features/external-docs.openapi.yaml

@@ -0,0 +1,148 @@
+openapi: 3.0.2
+
+info:
+  title: External Docs
+  version: "1"
+  
+externalDocs:
+  description: Read external docs
+  url: http://swagger.io
+
+tags:
+- name: pet
+  description: Everything about your Pets
+  externalDocs:
+    description: Pet Documentation
+    url: http://swagger.io
+- name: petWithoutDescription
+  externalDocs:
+    url: http://swagger.io
+
+paths:
+  /pet:
+    put:
+      externalDocs:
+        description: More details about putting a pet
+        url: http://swagger.io
+      tags:
+      - pet
+      summary: Update an existing pet
+      description: Update an existing pet by Id
+      operationId: updatePet
+      requestBody:
+        description: Update an existent pet in the store
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+        required: true
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        "400":
+          description: Invalid ID supplied
+        "404":
+          description: Pet not found
+        "405":
+          description: Validation exception
+    post:
+      externalDocs:
+        url: http://swagger.io
+      tags:
+      - pet
+      summary: Add a new pet to the store
+      description: Add a new pet to the store
+      operationId: addPet
+      requestBody:
+        description: Create a new pet in the store
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+        required: true
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        "405":
+          description: Invalid input
+
+components:
+  schemas:
+    Pet:
+      required:
+      - name
+      - photoUrls
+      type: object
+      description: This is a Pet
+      externalDocs:
+        description: More Docs About Pet
+        url: http://swagger.io
+      deprecated: true
+      properties:
+        id:
+          type: integer
+          format: int64
+          example: 10
+        name:
+          type: string
+          example: doggie
+        photoUrls:
+          type: array
+          items:
+            type: string
+        status:
+          type: string
+          description: pet status in the store
+          enum:
+          - available
+          - pending
+          - sold
+    Object:
+      type: object
+      externalDocs:
+        description: Object Docs
+        url: http://swagger.io
+      properties:
+        name:
+          type: string
+    ObjectWithoutDescription:
+      type: object
+      externalDocs:
+        url: http://swagger.io
+      properties:
+        name:
+          type: string
+    Primitive:
+      description: Just a string schema
+      type: string
+      externalDocs:
+        description: Primitive Docs
+        url: http://swagger.io
+    PrimitiveWithoutDescription:
+      description: Just a string schema
+      type: string
+      externalDocs:
+        url: http://swagger.io
+    Array:
+      description: Just an array schema
+      type: array
+      externalDocs:
+        description: Array Docs
+        url: http://swagger.io
+      items:
+        type: string
+    ArrayWithoutDescription:
+      description: Just an array schema
+      type: array
+      externalDocs:
+        url: http://swagger.io
+      items:
+        type: string

test/e2e-cypress/static/documents/features/external-docs.swagger.yaml

@@ -0,0 +1,116 @@
+swagger: "2.0"
+
+info:
+  title: External Docs
+  version: "1"
+  
+externalDocs:
+  description: Read external docs
+  url: http://swagger.io
+
+tags:
+- name: pet
+  description: Everything about your Pets
+  externalDocs:
+    description: Pet Documentation
+    url: http://swagger.io
+- name: petWithoutDescription
+  externalDocs:
+    url: http://swagger.io
+
+paths:
+  /pet:
+    put:
+      externalDocs:
+        description: More details about putting a pet
+        url: http://swagger.io
+      tags:
+      - pet
+      summary: Update an existing pet
+      description: Update an existing pet by Id
+      operationId: updatePet
+      responses:
+        200:
+          description: OK
+    post:
+      externalDocs:
+        url: http://swagger.io
+      tags:
+      - pet
+      summary: Add a new pet to the store
+      description: Add a new pet to the store
+      operationId: addPet
+      responses:
+        201:
+          description: Created
+
+definitions:
+  Pet:
+    required:
+    - name
+    - photoUrls
+    type: object
+    description: This is a Pet
+    externalDocs:
+      description: More Docs About Pet
+      url: http://swagger.io
+    properties:
+      id:
+        type: integer
+        format: int64
+        example: 10
+      name:
+        type: string
+        example: doggie
+      photoUrls:
+        type: array
+        items:
+          type: string
+      status:
+        type: string
+        description: pet status in the store
+        enum:
+        - available
+        - pending
+        - sold
+  Object:
+    type: object
+    externalDocs:
+      description: Object Docs
+      url: http://swagger.io
+    properties:
+      name:
+        type: string
+  ObjectWithoutDescription:
+    type: object
+    externalDocs:
+      url: http://swagger.io
+    properties:
+      name:
+        type: string
+  Primitive:
+    description: Just a string schema
+    type: string
+    externalDocs:
+      description: Primitive Docs
+      url: http://swagger.io
+  PrimitiveWithoutDescription:
+    description: Just a string schema
+    type: string
+    externalDocs:
+      url: http://swagger.io
+  Array:
+    description: Just an array schema
+    type: array
+    externalDocs:
+      description: Array Docs
+      url: http://swagger.io
+    items:
+      type: string
+  ArrayWithoutDescription:
+    description: Just an array schema
+    type: array
+    externalDocs:
+      url: http://swagger.io
+    items:
+      type: string

test/e2e-cypress/tests/features/external-docs.js

@@ -0,0 +1,108 @@
+describe("External docs feature", () => {
+  describe("in Swagger 2", () => {
+    ExternalDocsTest("/?url=/documents/features/external-docs.swagger.yaml")
+  })
+  describe("in OpenAPI 3", () => {
+    ExternalDocsTest("/?url=/documents/features/external-docs.openapi.yaml")
+  })
+})
+
+function ExternalDocsTest(baseUrl) {
+  describe("for Root", () => {
+    it("should display link to external docs with description", () => {
+      cy.visit(baseUrl)
+      .get(".info__extdocs")
+      .should("exist")
+      .and("contain.text", "Read external docs")
+      .and("have.attr", "href", "http://swagger.io")
+    })
+
+    it("should display link to external docs without description", () => {
+      cy
+        .intercept({
+          path: /^\/documents\/features\/external-docs\.(swagger|openapi)\.yaml\?intercept$/
+        }, (req) => {
+          delete req.headers["if-none-match"]
+          delete req.headers["if-modified-since"]
+          req.continue((res) => {
+            res.send({body: res.body.replace("  description: Read external docs\n", "")})
+          })
+        })
+        .visit(`${baseUrl}?intercept`)
+        .get(".info__extdocs")
+        .should("exist")
+        .and("contain.text", "http://swagger.io")
+        .and("have.attr", "href", "http://swagger.io")
+    })
+  })
+  
+  describe("for Tags", () => {
+    it("should display link to external docs with description", () => {
+      cy.visit(baseUrl)
+      .get(`.opblock-tag[data-tag="pet"] .info__externaldocs`)
+      .should("exist")
+      .find("a")
+      .should("contain.text", "Pet Documentation")
+      .and("have.attr", "href", "http://swagger.io")
+    })
+
+    it("should display link to external docs without description", () => {
+      cy.visit(baseUrl)
+      .get(`.opblock-tag[data-tag="petWithoutDescription"] .info__externaldocs`)
+      .should("exist")
+      .find("a")
+      .should("contain.text", "http://swagger.io")
+      .and("have.attr", "href", "http://swagger.io")
+    })
+  })
+
+  describe("for Schemas", () => {
+    function SchemaTestFactory(type) {
+      return () => {
+        it("should display link with description", () => {
+          cy.visit(baseUrl)
+          .get(`.models #model-${type} button`)
+          .click()
+          .get(`.models #model-${type} .external-docs a`)
+          .should("contain.text", `${type} Docs`)
+          .and("have.attr", "href", "http://swagger.io")
+        })
+
+        it("should display link without description", () => {
+          cy.visit(baseUrl)
+          .get(`.models #model-${type}WithoutDescription button`)
+          .click()
+          .get(`.models #model-${type}WithoutDescription .external-docs a`)
+          .should("contain.text", "http://swagger.io")
+          .and("have.attr", "href", "http://swagger.io")
+        })
+      }
+    }
+
+    describe("Primitive Schema", SchemaTestFactory("Primitive"))
+    describe("Array Schema", SchemaTestFactory("Array"))
+    describe("Object Schema", SchemaTestFactory("Object"))
+  })
+
+  describe("for Operation", () => {
+    it("should display link to external docs with description", () => {
+      cy.visit(baseUrl)
+      .get("#operations-pet-updatePet button")
+      .click()
+      .get("#operations-pet-updatePet .opblock-external-docs-wrapper .opblock-external-docs__description")
+      .should("contain.text", "More details about putting a pet")
+      .get("#operations-pet-updatePet .opblock-external-docs-wrapper .opblock-external-docs__link")
+      .should("have.attr", "href", "http://swagger.io")
+    })
+
+    it("should display link to external docs without description", () => {
+      cy.visit(baseUrl)
+      .get("#operations-pet-addPet button")
+      .click()
+      .get("#operations-pet-addPet .opblock-external-docs-wrapper .opblock-external-docs__description")
+      .should("not.exist")
+      .get("#operations-pet-addPet .opblock-external-docs-wrapper .opblock-external-docs__link")
+      .should("have.attr", "href", "http://swagger.io")
+    })
+  })
+}