feat: Render external docs links and descriptions (#7559)
Co-authored-by: Tim Lai <timothy.lai@smartbear.com>
This commit is contained in:
Fabian Schneider
@@ -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
|
||||
@@ -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
|
||||
108
test/e2e-cypress/tests/features/external-docs.js
Normal file
108
test/e2e-cypress/tests/features/external-docs.js
Normal file
@@ -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")
|
||||
})
|
||||
})
|
||||
}
|
||||
Reference in New Issue
Block a user