Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2025-08-01 19:00:21 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into chore/fix-vulnerabilities-and-update-libs

Browse Source
This commit is contained in:
Alex Varchuk 2024-04-24 15:21:29 +03:00
commit ffd5cdd449
No known key found for this signature in database
GPG Key ID: 8A9260AE529FF454
21 changed files with 1084 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
.github/styles/Vocab/Rules/accept.txt → .github/styles/config/vocabularies/Rules/accept.txt vendored
View File

0
.github/styles/Vocab/Rules/reject.txt → .github/styles/config/vocabularies/Rules/reject.txt vendored
View File

37
.github/workflows/docs-tests.yaml vendored Normal file
View File

@ -0,0 +1,37 @@
name: Documentation tests
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
markdownlint:
name: markdownlint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DavidAnson/markdownlint-cli2-action@v15
with:
config: .markdownlint.yaml
globs: |
docs/**/*.md
README.md
vale:
name: vale action
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: errata-ai/vale-action@reviewdog
with:
files: '["README.md", "docs"]'
filter_mode: file
linkcheck:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Markup Link Checker (mlc)
uses: becheran/mlc@v0.16.1
with:
args: ./docs

16
.github/workflows/vale.yaml vendored
View File

@ -1,16 +0,0 @@
name: Docs lint
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
vale:
name: vale action
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: errata-ai/vale-action@reviewdog
with:
files: '["README.md", "docs"]'
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

54
.markdownlint.yaml Normal file
View File

@ -0,0 +1,54 @@
---
# Default rules: https://github.com/github/super-linter/blob/master/TEMPLATES/.markdown-lint.yml
# Rules by id
# Unordered list style
MD004: false
# Unordered list indentation
MD007:
indent: 2
MD013:
# TODO: Consider to decrease allowed line length
line_length: 800
tables: false
## Allow same headers in siblings
MD024:
siblings_only: true
# Multiple top level headings in the same document
MD025:
front_matter_title: ''
# Trailing punctuation in heading
MD026:
punctuation: '.,;:。，；:'
# Ordered list item prefix
MD029: false
# Unordered lists inside of ordered lists
MD030: false
# Inline HTML
MD033: false
# No bare urls
MD034: false
# Emphasis used instead of a heading
MD036: false
# Disable "First line in file should be a top level heading"
# We use uncommon format to add metadata.
# TODO: Consider to use "YAML front matter".
MD041: false
# Rules by tags
blank_lines: false
MD046: false
# code-block-style

4
.mlc.toml Normal file
View File

@ -0,0 +1,4 @@
# Ignore these links, we can't check them from this subproject
ignore-links=["../*", "/docs/*"]
# Path to the root folder used to resolve all relative paths
root-dir="./docs"

15
README.md
View File

@ -1,11 +1,11 @@
<div align="center"> <div align="center">
<img alt="Redoc logo" src="https://raw.githubusercontent.com/Redocly/redoc/main//docs/images/redoc.png" width="400px" /> <img alt="Redoc logo" src="https://raw.githubusercontent.com/Redocly/redoc/main//docs/images/redoc.png" width="400px" />
# Generate interactive API documentation from OpenAPI definitions # Generate beautiful API documentation from OpenAPI
[![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE) [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE)
[![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) [![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![jsDelivr status](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc)
</div> </div>
@ -34,13 +34,11 @@ enter the URL for your definition and select **TRY IT**.
- Responsive three-panel design with menu/scrolling synchronization - Responsive three-panel design with menu/scrolling synchronization
- Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0 - Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0
- [Multiple deployment options](https://redocly.com/docs/redoc/)
- Interactive interface so your users can try the API immediately
- Ability to integrate your API introduction into the side menu - Ability to integrate your API introduction into the side menu
- High-level grouping in side menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - High-level grouping in side menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension
- [Simple integration with `create-react-app`](https://redocly.com/docs/redoc/quickstart/react/) - [Simple integration with `create-react-app`](https://redocly.com/docs/redoc/quickstart/react/)
- Code samples support (with vendor extension) <br> - Code samples support (with vendor extension) <br>
![](docs/images/code-samples-demo.gif) ![code samples in action](docs/images/code-samples-demo.gif)
## Usage ## Usage
@ -50,7 +48,7 @@ Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag,
If you have Node installed, quickly generate documentation using `npx`: If you have Node installed, quickly generate documentation using `npx`:
``` ```bash
npx @redocly/cli build-docs openapi.yaml npx @redocly/cli build-docs openapi.yaml
``` ```
@ -73,9 +71,9 @@ Add your own `spec-url` to the `<redoc>` tag; this attribute can also be a local
### More usage options ### More usage options
Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each. Check out the [deployment documentation](./docs/deployment/intro.md) for more options, and detailed documentation for each.
## Redoc vs. Reference ## Redoc vs. Redocly API Reference
Redoc is Redocly's community-edition product. Looking for something more? Redoc is Redocly's community-edition product. Looking for something more?
We also offer [hosted API reference documentation](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/) We also offer [hosted API reference documentation](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/)
@ -104,6 +102,7 @@ A sample of the organizations using Redocly tools in the wild:
- [Commbox](https://www.commbox.io/api/) - [Commbox](https://www.commbox.io/api/)
- [APIs.guru](https://apis.guru/api-doc/) - [APIs.guru](https://apis.guru/api-doc/)
- [BoxKnight](https://www.docs.boxknight.com/) - [BoxKnight](https://www.docs.boxknight.com/)
- [Quaderno API](https://developers.quaderno.io/api)
_Pull requests to add your own API page to the list are welcome_ _Pull requests to add your own API page to the list are welcome_

93
demo/index.html
View File

@ -1,46 +1,63 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head>
<meta charset="UTF-8" />
<title>Redoc Interactive Demo</title>
<meta
name="description"
content="Redoc Interactive Demo. OpenAPI-generated API Reference Documentation"
/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<head> <meta property="og:title" content="Redoc Interactive Demo" />
<meta charset="UTF-8" /> <meta
<title>ReDoc Interactive Demo</title> property="og:description"
<meta name="description" content="ReDoc Interactive Demo. OpenAPI/Swagger-generated API Reference Documentation" /> content="Redoc Interactive Demo. OpenAPI-generated API Reference Documentation"
<meta name="viewport" content="width=device-width, initial-scale=1"> />
<meta
property="og:image"
content="https://user-images.githubusercontent.com/3975738/37729752-8a9ea38a-2d46-11e8-8438-42ed26bf1751.png"
/>
<meta name="twitter:card" content="summary_large_image" />
<meta property="og:title" content="ReDoc Interactive Demo"> <style>
<meta property="og:description" content="ReDoc Interactive Demo. OpenAPI/Swagger-generated API Reference Documentation"> body {
<meta property="og:image" content="https://user-images.githubusercontent.com/3975738/37729752-8a9ea38a-2d46-11e8-8438-42ed26bf1751.png"> margin: 0;
<meta name="twitter:card" content="summary_large_image"> padding: 0;
}
<style> redoc {
body { display: block;
margin: 0; }
padding: 0; </style>
} <link
href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
rel="stylesheet"
/>
</head>
redoc { <body>
display: block; <div id="container"></div>
}
</style>
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body> <script>
<div id="container"> </div> (function (i, s, o, g, r, a, m) {
i['GoogleAnalyticsObject'] = r;
(i[r] =
i[r] ||
function () {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga');
<script> if (window.location.host === 'rebilly.github.io') {
(function (i, s, o, g, r, a, m) { ga('create', 'UA-81703547-1', 'auto');
i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function () { ga('send', 'pageview');
(i[r].q = i[r].q || []).push(arguments) }
}, i[r].l = 1 * new Date(); a = s.createElement(o), </script>
m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m) </body>
})(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga'); </html>
if (window.location.host === 'rebilly.github.io') {
ga('create', 'UA-81703547-1', 'auto');
ga('send', 'pageview');
}
</script>
</body>
</html>

9
demo/index.tsx
View File

@ -5,11 +5,12 @@ import { RedocStandalone } from '../src';
import ComboBox from './ComboBox'; import ComboBox from './ComboBox';
import FileInput from './components/FileInput'; import FileInput from './components/FileInput';
const DEFAULT_SPEC = 'openapi.yaml'; const DEFAULT_SPEC = 'museum.yaml';
const NEW_VERSION_SPEC = 'openapi-3-1.yaml'; const NEW_VERSION_PETSTORE = 'openapi-3-1.yaml';
const demos = [ const demos = [
{ value: NEW_VERSION_SPEC, label: 'Petstore OpenAPI 3.1' }, { value: DEFAULT_SPEC, label: 'Museum API' },
{ value: NEW_VERSION_PETSTORE, label: 'Petstore OpenAPI 3.1' },
{ value: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml', label: 'Instagram' }, { value: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml', label: 'Instagram' },
{ {
value: 'https://api.apis.guru/v2/specs/googleapis.com/calendar/v3/openapi.yaml', value: 'https://api.apis.guru/v2/specs/googleapis.com/calendar/v3/openapi.yaml',
@ -54,7 +55,7 @@ class DemoApp extends React.Component<
}; };
handleChange = (url: string) => { handleChange = (url: string) => {
if (url === NEW_VERSION_SPEC) { if (url === NEW_VERSION_PETSTORE) {
this.setState({ cors: false }); this.setState({ cors: false });
0; 0;
} }

BIN
demo/museum-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 KiB

772
demo/museum.yaml Normal file
View File

@ -0,0 +1,772 @@
openapi: 3.1.0
info:
title: Redocly Museum API
description: An imaginary, but delightful Museum API for interacting with museum services and information. Built with love by Redocly.
version: 1.0.0
contact:
email: team@redocly.com
url: 'https://redocly.com/docs/cli/'
x-logo:
url: 'https://redocly.github.io/redoc/museum-logo.png'
altText: Museum logo
license:
name: MIT
url: 'https://opensource.org/license/mit/ '
servers:
- url: 'https://api.fake-museum-example.com/v1'
paths:
/museum-hours:
get:
summary: Get museum hours
description: Get upcoming museum operating hours
operationId: getMuseumHours
tags:
- Operations
parameters:
- $ref: '#/components/parameters/StartDate'
- $ref: '#/components/parameters/PaginationPage'
- $ref: '#/components/parameters/PaginationLimit'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetMuseumHoursResponse'
examples:
default:
summary: Museum opening hours
value:
- date: '2023-09-11'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-12'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-13'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-17'
timeOpen: '09:00'
timeClose: '18:00'
closed:
summary: The museum is closed
value: []
'400':
description: Bad request
'404':
description: Not found
/special-events:
post:
security: []
operationId: CreateSpecialEvent
summary: Create special event
tags:
- Events
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpecialEventRequest'
examples:
default_example:
$ref: '#/components/examples/CreateSpecialEventRequestExample'
responses:
'200':
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/SpecialEventResponse'
examples:
default_example:
$ref: '#/components/examples/CreateSpecialEventResponseExample'
'400':
description: Bad request
'404':
description: Not found
get:
summary: List special events
description: Return a list of upcoming special events at the museum.
security: []
operationId: listSpecialEvents
tags:
- Events
parameters:
- name: startDate
in: query
description: The starting date to retrieve future operating hours from. Defaults to today's date.
schema:
type: string
format: date
example: 2023-02-23
- name: endDate
in: query
description: The end of a date range to retrieve special events for. Defaults to 7 days after `startDate`.
schema:
type: string
format: date
example: 2023-04-18
- name: page
in: query
description: The page number to retrieve.
schema:
type: integer
default: 1
example: 2
- name: limit
in: query
description: The number of days per page.
schema:
type: integer
default: 10
maximum: 30
example: 15
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListSpecialEventsResponse'
examples:
default_example:
$ref: '#/components/examples/ListSpecialEventsResponseExample'
'400':
description: Bad request
'404':
description: Not found
/special-events/{eventId}:
get:
summary: Get special event
description: Get details about a special event.
operationId: getSpecialEvent
tags:
- Events
parameters:
- $ref: '#/components/parameters/EventId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SpecialEventResponse'
examples:
default_example:
$ref: '#/components/examples/GetSpecialEventResponseExample'
'400':
description: Bad request
'404':
description: Not found
patch:
summary: Update special event
description: Update the details of a special event
operationId: updateSpecialEvent
tags:
- Events
parameters:
- $ref: '#/components/parameters/EventId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSpecialEventRequest'
examples:
default_example:
$ref: '#/components/examples/UpdateSpecialEventRequestExample'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SpecialEventResponse'
examples:
default_example:
$ref: '#/components/examples/UpdateSpecialEventResponseExample'
'400':
description: Bad request
'404':
description: Not found
delete:
summary: Delete special event
description: Delete a special event from the collection. Allows museum to cancel planned events.
operationId: deleteSpecialEvent
tags:
- Events
parameters:
- $ref: '#/components/parameters/EventId'
responses:
'204':
description: Success - no content
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
/tickets:
post:
summary: Buy museum tickets
description: Purchase museum tickets for general entry or special events.
operationId: buyMuseumTickets
tags:
- Tickets
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BuyMuseumTicketsRequest'
examples:
general_entry:
$ref: '#/components/examples/BuyGeneralTicketsRequestExample'
event_entry:
$ref: '#/components/examples/BuyEventTicketsRequestExample'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BuyMuseumTicketsResponse'
examples:
general_entry:
$ref: '#/components/examples/BuyGeneralTicketsResponseExample'
event_entry:
$ref: '#/components/examples/BuyEventTicketsResponseExample'
'400':
description: Bad request
'404':
description: Not found
/tickets/{ticketId}/qr:
get:
summary: Get ticket QR code
description: Return an image of your ticket with scannable QR code. Used for event entry.
operationId: getTicketCode
tags:
- Tickets
parameters:
- $ref: '#/components/parameters/TicketId'
responses:
'200':
description: Scannable event ticket in image format
content:
image/png:
schema:
$ref: '#/components/schemas/GetTicketCodeResponse'
'400':
description: Bad request
'404':
description: Not found
components:
schemas:
SpecialEvent:
description: Request payload for creating new special events at the museum.
properties:
name:
description: Name of the special event
type: string
example: Fossil lecture
location:
description: Location where the special event is held
type: string
example: Lecture theatre
eventDescription:
description: Description of the special event
type: string
example: Our panel of experts will share their favorite fossils and explain why they are so great.
dates:
description: List of planned dates for the special event
type: array
items:
type: string
format: date
example: 2024-03-29
price:
description: Price of a ticket for the special event
type: number
format: float
example: 12.50
TicketType:
description: Type of ticket being purchased. Use `general` for regular museum entry and `event` for tickets to special events.
type: string
enum:
- event
- general
example: event
Date:
type: string
format: date
example: 2023-10-29
Email:
description: Email address for ticket purchaser.
type: string
format: email
example: museum-lover@example.com
Phone:
description: Phone number for the ticket purchaser (optional).
type: string
example: +1(234)-567-8910
BuyMuseumTicketsRequest:
description: Request payload used for purchasing museum tickets.
type: object
properties:
ticketType:
$ref: '#/components/schemas/TicketType'
eventId:
description: Unique identifier for a special event. Required if purchasing tickets for the museum's special events.
$ref: '#/components/schemas/EventId'
ticketDate:
description: Date that the ticket is valid for.
$ref: '#/components/schemas/Date'
email:
$ref: '#/components/schemas/Email'
phone:
$ref: '#/components/schemas/Phone'
required:
- ticketType
- ticketDate
- email
TicketMessage:
description: Confirmation message after a ticket purchase.
type: string
example: Museum general entry ticket purchased
TicketId:
description: Unique identifier for museum ticket. Generated when purchased.
type: string
format: uuid
example: a54a57ca-36f8-421b-a6b4-2e8f26858a4c
TicketConfirmation:
description: Unique confirmation code used to verify ticket purchase.
type: string
example: ticket-event-a98c8f-7eb12
BuyMuseumTicketsResponse:
description: Details for a museum ticket after a successful purchase.
type: object
properties:
message:
$ref: '#/components/schemas/TicketMessage'
eventName:
$ref: '#/components/schemas/EventName'
ticketId:
$ref: '#/components/schemas/TicketId'
ticketType:
$ref: '#/components/schemas/TicketType'
ticketDate:
description: Date the ticket is valid for.
$ref: '#/components/schemas/Date'
confirmationCode:
$ref: '#/components/schemas/TicketConfirmation'
required:
- message
- ticketId
- ticketType
- ticketDate
- confirmationCode
GetTicketCodeResponse:
description: An image of a ticket with a QR code used for museum or event entry.
type: string
format: binary
GetMuseumHoursResponse:
description: List of museum operating hours for consecutive days.
type: array
items:
$ref: '#/components/schemas/MuseumDailyHours'
MuseumDailyHours:
description: Daily operating hours for the museum.
type: object
properties:
date:
description: Date the operating hours apply to.
$ref: '#/components/schemas/Date'
example: 2024-12-31
timeOpen:
type: string
pattern: '^([01]\d|2[0-3]):?([0-5]\d)$'
description: Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).
example: 09:00
timeClose:
description: Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).
type: string
pattern: '^([01]\d|2[0-3]):?([0-5]\d)$'
example: 18:00
required:
- date
- timeOpen
- timeClose
EventId:
description: Identifier for a special event.
type: string
format: uuid
example: 3be6453c-03eb-4357-ae5a-984a0e574a54
EventName:
type: string
description: Name of the special event
example: Pirate Coding Workshop
EventLocation:
type: string
description: Location where the special event is held
example: Computer Room
EventDescription:
type: string
description: Description of the special event
example: Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang).
EventDates:
type: array
items:
$ref: '#/components/schemas/Date'
description: List of planned dates for the special event
EventPrice:
description: Price of a ticket for the special event
type: number
format: float
example: 25
CreateSpecialEventRequest:
description: Request payload for creating new special events at the museum.
properties:
name:
$ref: '#/components/schemas/EventName'
location:
$ref: '#/components/schemas/EventLocation'
eventDescription:
$ref: '#/components/schemas/EventDescription'
dates:
$ref: '#/components/schemas/EventDates'
price:
$ref: '#/components/schemas/EventPrice'
required:
- name
- location
- eventDescription
- dates
- price
UpdateSpecialEventRequest:
description: Request payload for updating an existing special event. Only included fields are updated in the event.
properties:
name:
$ref: '#/components/schemas/EventName'
location:
$ref: '#/components/schemas/EventLocation'
eventDescription:
$ref: '#/components/schemas/EventDescription'
dates:
$ref: '#/components/schemas/EventDates'
price:
$ref: '#/components/schemas/EventPrice'
ListSpecialEventsResponse:
description: A list of upcoming special events
type: array
items:
$ref: '#/components/schemas/SpecialEventResponse'
SpecialEventResponse:
description: Information about a special event.
properties:
eventId:
$ref: '#/components/schemas/EventId'
name:
$ref: '#/components/schemas/EventName'
location:
$ref: '#/components/schemas/EventLocation'
eventDescription:
$ref: '#/components/schemas/EventDescription'
dates:
$ref: '#/components/schemas/EventDates'
price:
$ref: '#/components/schemas/EventPrice'
required:
- eventId
- name
- location
- eventDescription
- dates
- price
securitySchemes:
MuseumPlaceholderAuth:
type: http
scheme: basic
examples:
BuyGeneralTicketsRequestExample:
summary: General entry ticket
value:
ticketType: general
ticketDate: 2023-09-07
email: todd@example.com
BuyEventTicketsRequestExample:
summary: Special event ticket
value:
ticketType: general
eventId: dad4bce8-f5cb-4078-a211-995864315e39
ticketDate: 2023-09-05
email: todd@example.com
BuyGeneralTicketsResponseExample:
summary: General entry ticket
value:
message: Museum general entry ticket purchased
ticketId: 382c0820-0530-4f4b-99af-13811ad0f17a
ticketType: general
ticketDate: 2023-09-07
confirmationCode: ticket-general-e5e5c6-dce78
BuyEventTicketsResponseExample:
summary: Special event ticket
value:
message: Museum special event ticket purchased
ticketId: b811f723-17b2-44f7-8952-24b03e43d8a9
eventName: Mermaid Treasure Identification and Analysis
ticketType: event
ticketDate: 2023-09-05
confirmationCode: ticket-event-9c55eg-8v82a
CreateSpecialEventRequestExample:
summary: Create special event
value:
name: Mermaid Treasure Identification and Analysis
location: Under the seaaa 🦀 🎶 🌊.
eventDescription: Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.
dates:
- 2023-09-05
- 2023-09-08
price: 0
CreateSpecialEventResponseExample:
summary: Special event created
value:
eventId: dad4bce8-f5cb-4078-a211-995864315e39
name: Mermaid Treasure Identification and Analysis
location: Under the seaaa 🦀 🎶 🌊.
eventDescription: Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.
dates:
- 2023-09-05
- 2023-09-08
price: 30
GetSpecialEventResponseExample:
summary: Get special event
value:
eventId: 6744a0da-4121-49cd-8479-f8cc20526495
name: Time Traveler Tea Party
location: Temporal Tearoom
eventDescription: Sip tea with important historical figures.
dates:
- 2023-11-18
- 2023-11-25
- 2023-12-02
price: 60
ListSpecialEventsResponseExample:
summary: List of special events
value:
- eventId: f3e0e76e-e4a8-466e-ab9c-ae36c15b8e97
name: Sasquatch Ballet
location: Seattle... probably
eventDescription: They're big, they're hairy, but they're also graceful. Come learn how the biggest feet can have the lightest touch.
dates:
- 2023-12-15
- 2023-12-22
price: 40
- eventId: 2f14374a-9c65-4ee5-94b7-fba66d893483
name: Solar Telescope Demonstration
location: Far from the sun.
eventDescription: Look at the sun without going blind!
dates:
- 2023-09-07
- 2023-09-14
price: 50
- eventId: 6aaa61ba-b2aa-4868-b803-603dbbf7bfdb
name: Cook like a Caveman
location: Fire Pit on East side
eventDescription: Learn to cook on an open flame.
dates:
- 2023-11-10
- 2023-11-17
- 2023-11-24
price: 5
- eventId: 602b75e1-5696-4ab8-8c7a-f9e13580f910
name: Underwater Basket Weaving
location: Rec Center Pool next door.
eventDescription: Learn to weave baskets underwater.
dates:
- 2023-09-12
- 2023-09-15
price: 15
- eventId: dad4bce8-f5cb-4078-a211-995864315e39
name: Mermaid Treasure Identification and Analysis
location: Room Sea-12
eventDescription: Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits — kindly donated by Ariel.
dates:
- 2023-09-05
- 2023-09-08
price: 30
- eventId: 6744a0da-4121-49cd-8479-f8cc20526495
name: Time Traveler Tea Party
location: Temporal Tearoom
eventDescription: Sip tea with important historical figures.
dates:
- 2023-11-18
- 2023-11-25
- 2023-12-02
price: 60
- eventId: 3be6453c-03eb-4357-ae5a-984a0e574a54
name: Pirate Coding Workshop
location: Computer Room
eventDescription: Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang).
dates:
- 2023-10-29
- 2023-10-30
- 2023-10-31
price: 45
- eventId: 9d90d29a-2af5-4206-97d9-9ea9ceadcb78
name: Llama Street Art Through the Ages
location: Auditorium
eventDescription: Llama street art?! Alpaca my bags -- let's go!
dates:
- 2023-10-29
- 2023-10-30
- 2023-10-31
price: 45
- eventId: a3c7b2c4-b5fb-4ef7-9322-00a919864957
name: The Great Parrot Debate
location: Outdoor Amphitheatre
eventDescription: See leading parrot minds discuss important geopolitical issues.
dates:
- 2023-11-03
- 2023-11-10
price: 35
- eventId: b92d46b7-4c5d-422b-87a5-287767e26f29
name: Eat a Bunch of Corn
location: Cafeteria
eventDescription: We accidentally bought too much corn. Please come eat it.
dates:
- 2023-11-10
- 2023-11-17
- 2023-11-24
price: 5
UpdateSpecialEventRequestExample:
summary: Update special event request
value:
location: On the beach.
price: 15
UpdateSpecialEventResponseExample:
summary: Update special event
value:
eventId: dad4bce8-f5cb-4078-a211-995864315e39
name: Mermaid Treasure Identification and Analysis
location: On the beach.
eventDescription: Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.
dates:
- 2023-09-05
- 2023-09-08
price: 15
GetMuseumHours:
summary: Museum opening hours
value:
- date: '2023-09-11'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-12'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-13'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-14'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-15'
timeOpen: '10:00'
timeClose: '16:00'
- date: '2023-09-18'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-19'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-20'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-21'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-22'
timeOpen: '10:00'
timeClose: '16:00'
ClosedMuseumHours:
summary: The museum is closed
value: []
parameters:
PaginationPage:
name: page
in: query
description: The page number to retrieve.
schema:
type: integer
default: 1
example: 2
PaginationLimit:
name: limit
in: query
description: The number of days per page.
schema:
type: integer
default: 10
maximum: 30
example: 15
EventId:
name: eventId
in: path
description: An identifier for a special event.
required: true
schema:
type: string
format: uuid
example: dad4bce8-f5cb-4078-a211-995864315e39
StartDate:
name: startDate
in: query
description: The starting date to retrieve future operating hours from. Defaults to today's date.
schema:
type: string
format: date
example: 2023-02-23
EndDate:
name: endDate
in: query
description: The end of a date range to retrieve special events for. Defaults to 7 days after `startDate`.
schema:
type: string
format: date
example: 2023-04-18
TicketId:
name: ticketId
in: path
description: An identifier for a ticket to a museum event. Used to generate ticket image.
required: true
schema:
type: string
format: uuid
example: a54a57ca-36f8-421b-a6b4-2e8f26858a4c
tags:
- name: Operations
x-displayName: About the museum
description: Operational information about the museum.
- name: Events
x-displayName: Upcoming events
description: Special events hosted by the Museum.
- name: Tickets
x-displayName: Buy tickets
description: Museum tickets for general entrance or special events.
x-tagGroups:
- name: Plan your visit
tags:
- Operations
- Events
- name: Purchases
tags:
- Tickets
security:
- MuseumPlaceholderAuth: []

2
demo/playground/hmr-playground.tsx
View File

@ -9,7 +9,7 @@ const swagger = window.location.search.indexOf('swagger') > -1;
const userUrl = window.location.search.match(/url=(.*)$/); const userUrl = window.location.search.match(/url=(.*)$/);
const specUrl = const specUrl =
(userUrl && userUrl[1]) || (swagger ? 'swagger.yaml' : big ? 'big-openapi.json' : 'openapi.yaml'); (userUrl && userUrl[1]) || (swagger ? 'museum.yaml' : big ? 'big-openapi.json' : 'museum.yaml');
const options: RedocRawOptions = { nativeScrollbars: false, maxDisplayedEnumValues: 3 }; const options: RedocRawOptions = { nativeScrollbars: false, maxDisplayedEnumValues: 3 };

43
demo/playground/index.html
View File

@ -1,25 +1,26 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Redoc</title>
<style>
body {
margin: 0;
padding: 0;
}
<head> redoc {
<meta charset="UTF-8" /> display: block;
<meta name="viewport" content="width=device-width, initial-scale=1"> }
<title>ReDoc</title> </style>
<style> <link
body { href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
margin: 0; rel="stylesheet"
padding: 0; />
} </head>
redoc { <body>
display: block; <redoc id="example"></redoc>
} </body>
</style> </html>
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
<redoc id="example"></redoc>
</body>
</html>

2
demo/webpack.config.ts
View File

@ -121,7 +121,7 @@ export default (env: { playground?: boolean; bench?: boolean } = {}, { mode }) =
webpackIgnore(/json-schema-ref-parser\/lib\/dereference\.js/), webpackIgnore(/json-schema-ref-parser\/lib\/dereference\.js/),
webpackIgnore(/^\.\/SearchWorker\.worker$/), webpackIgnore(/^\.\/SearchWorker\.worker$/),
new CopyWebpackPlugin({ new CopyWebpackPlugin({
patterns: ['demo/openapi.yaml'], patterns: ['demo/museum.yaml'],
}), }),
], ],
}); });

6
docs/config.md
View File

@ -6,12 +6,12 @@ Each deployment type has documentation on how to configure options for that type
**Versions: 2.x** **Versions: 2.x**
:::success Client-side configuration {% admonition type="success" name="Client-side configuration" %}
Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case).
For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`.
::: {% /admonition %}
## Functional settings ## Functional settings

4
docs/deployment/cli.md
View File

@ -12,9 +12,9 @@ With Redocly CLI, you can bundle your OpenAPI definition and API documentation
First, you need to install the `@redocly/cli` package. First, you need to install the `@redocly/cli` package.
You can install it [globally](/docs/cli/installation.md#install-globally) using npm or Yarn. You can install it [globally](../../cli/installation.md#install-globally) using npm or Yarn.
Or you can install it during [runtime](/docs/cli/installation.md#use-npx-at-runtime) using npx or Docker. Or you can install it during [runtime](../../cli/installation.md#use-npx-at-runtime) using npx or Docker.
## Step 2 - Build the HTML file ## Step 2 - Build the HTML file

2
docs/deployment/html.md
View File

@ -126,7 +126,7 @@ The main example shows using the CDN:
If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`: If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`:
``` ```sh
npm install redoc npm install redoc
``` ```

4
docs/deployment/intro.md
View File

@ -30,8 +30,8 @@ The following options are supported:
You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions: You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:
- OpenAPI 3.0 - OpenAPI 3.0
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml) - [Museum Example API](https://github.com/Redocly/museum-openapi-example/blob/main/openapi.yaml)
- [Swagger Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json) - [Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json)
- OpenAPI 2.0 - OpenAPI 2.0
- [Thingful OpenAPI Definition](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml) - [Thingful OpenAPI Definition](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml)
- [Fitbit Plus OpenAPI Definition](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml) - [Fitbit Plus OpenAPI Definition](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml)

4
docs/index.md
View File

@ -28,7 +28,7 @@ Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag,
If you have Node installed, quickly generate documentation using `npx`: If you have Node installed, quickly generate documentation using `npx`:
``` ```sh
npx @redocly/cli build-docs openapi.yaml npx @redocly/cli build-docs openapi.yaml
``` ```
@ -84,7 +84,7 @@ theme:
Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this: Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this:
``` ```sh
redocly preview-docs openapi.yaml redocly preview-docs openapi.yaml
``` ```

224
docs/redoc-vendor-extensions.md
View File

@ -3,78 +3,79 @@
You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc. You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc.
- [Redoc vendor extensions](#redoc-vendor-extensions) - [Redoc vendor extensions](#redoc-vendor-extensions)
- [Swagger Object](#swagger-object) - [Swagger Object](#swagger-object)
- [x-servers](#x-servers) - [x-servers](#x-servers)
- [x-tagGroups](#x-taggroups) - [x-tagGroups](#x-taggroups)
- [How to use with Redoc](#how-to-use-with-redoc) - [How to use with Redoc](#how-to-use-with-redoc)
- [Tag Group Object](#tag-group-object) - [Tag Group Object](#tag-group-object)
- [Fixed fields](#fixed-fields) - [Fixed fields](#fixed-fields)
- [x-tagGroups example](#x-taggroups-example) - [x-tagGroups example](#x-taggroups-example)
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters) - [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
- [How to use with Redoc](#how-to-use-with-redoc-1) - [How to use with Redoc](#how-to-use-with-redoc-1)
- [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example) - [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example)
- [Info Object](#info-object) - [Info Object](#info-object)
- [x-logo](#x-logo) - [x-logo](#x-logo)
- [How to use with Redoc](#how-to-use-with-redoc-2) - [How to use with Redoc](#how-to-use-with-redoc-2)
- [Logo Object](#logo-object) - [Logo Object](#logo-object)
- [Fixed fields](#fixed-fields-1) - [Fixed fields](#fixed-fields-1)
- [x-logo example](#x-logo-example) - [x-logo example](#x-logo-example)
- [Tag Object](#tag-object) - [Tag Object](#tag-object)
- [x-traitTag](#x-traittag) - [x-traitTag](#x-traittag)
- [How to use with Redoc](#how-to-use-with-redoc-3) - [How to use with Redoc](#how-to-use-with-redoc-3)
- [x-traitTag example](#x-traittag-example) - [x-traitTag example](#x-traittag-example)
- [x-displayName](#x-displayname) - [x-displayName](#x-displayname)
- [Operation Object vendor extensions](#operation-object-vendor-extensions) - [Operation Object vendor extensions](#operation-object-vendor-extensions)
- [x-codeSamples](#x-codesamples) - [x-codeSamples](#x-codesamples)
- [How to use with Redoc](#how-to-use-with-redoc-4) - [How to use with Redoc](#how-to-use-with-redoc-4)
- [Code Sample Object](#code-sample-object) - [Code Sample Object](#code-sample-object)
- [Fixed fields](#fixed-fields-2) - [Fixed fields](#fixed-fields-2)
- [Code Sample Object example](#code-sample-object-example) - [Code Sample Object example](#code-sample-object-example)
- [Parameter Object](#parameter-object) - [Parameter Object](#parameter-object)
- [x-examples](#x-examples) - [x-examples](#x-examples)
- [How to use with Redoc](#how-to-use-with-redoc-5) - [How to use with Redoc](#how-to-use-with-redoc-5)
- [Response Object vendor extensions](#response-object-vendor-extensions) - [Response Object vendor extensions](#response-object-vendor-extensions)
- [x-summary](#x-summary) - [x-summary](#x-summary)
- [How to use with Redoc](#how-to-use-with-redoc-6) - [How to use with Redoc](#how-to-use-with-redoc-6)
- [Schema Object](#schema-object) - [Schema Object](#schema-object)
- [x-nullable](#x-nullable) - [x-nullable](#x-nullable)
- [How to use with Redoc](#how-to-use-with-redoc-7) - [How to use with Redoc](#how-to-use-with-redoc-7)
- [x-extendedDiscriminator](#x-extendeddiscriminator) - [x-extendedDiscriminator](#x-extendeddiscriminator)
- [How to use with Redoc](#how-to-use-with-redoc-8) - [How to use with Redoc](#how-to-use-with-redoc-8)
- [x-extendedDiscriminator example](#x-extendeddiscriminator-example) - [x-extendedDiscriminator example](#x-extendeddiscriminator-example)
- [x-additionalPropertiesName](#x-additionalpropertiesname) - [x-additionalPropertiesName](#x-additionalpropertiesname)
- [How to use with Redoc](#how-to-use-with-redoc-9) - [How to use with Redoc](#how-to-use-with-redoc-9)
- [x-additionalPropertiesName example](#x-additionalpropertiesname-example) - [x-additionalPropertiesName example](#x-additionalpropertiesname-example)
- [x-explicitMappingOnly](#x-explicitmappingonly) - [x-explicitMappingOnly](#x-explicitmappingonly)
- [How to use with Redoc](#how-to-use-with-redoc-10) - [How to use with Redoc](#how-to-use-with-redoc-10)
- [x-explicitMappingOnly example](#x-explicitmappingonly-example) - [x-explicitMappingOnly example](#x-explicitmappingonly-example)
### Swagger Object ## Swagger Object
Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi-1/)
#### x-servers ### x-servers
Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Currently doesn't support templates. Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Currently doesn't support templates.
#### x-tagGroups ### x-tagGroups
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :-----------: | :---------- | | :------------- | :-----------: | :---------- |
| x-tagGroups | [ [Tag Group Object](#tag-group-object) ] | A list of tag groups | | x-tagGroups | [ [Tag Group Object](#tag-group-object) ] | A list of tag groups |
###### How to use with Redoc #### How to use with Redoc
`x-tagGroups` is used to group tags in the side menu. `x-tagGroups` is used to group tags in the side menu.
Before you use `x-tagGroups`, make sure you **add all tags to a group**, since a tag that is not in a group, **is not displayed** at all! Before you use `x-tagGroups`, make sure you **add all tags to a group**, since a tag that is not in a group, **is not displayed** at all!
<a name="tagGroupObject"></a> <a name="tagGroupObject"></a>
#### Tag Group Object #### Tag Group Object
Information about tags group Information about tags group
###### Fixed fields ##### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :---------- | :--------: | :---------- | | :---------- | :--------: | :---------- |
| name | string | The group name | | name | string | The group name |
| tags | [ string ] | List of tags to include in this group | tags | [ string ] | List of tags to include in this group |
###### x-tagGroups example #### x-tagGroups example
json json
```json ```json
{ {
@ -104,18 +105,18 @@ x-tagGroups:
- Secondary Stats - Secondary Stats
``` ```
#### x-ignoredHeaderParameters ### x-ignoredHeaderParameters
| Field Name | Type | Description | | Field Name | Type | Description |
| :-------------------------- | :-----------: | :---------- | | :-------------------------- | :-----------: | :---------- |
| x-ignoredHeaderParameters | [ string ] | A list of ignored headers | | x-ignoredHeaderParameters | [ string ] | A list of ignored headers |
###### How to use with Redoc #### How to use with Redoc
Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc. Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc.
###### x-ignoredHeaderParameters example #### x-ignoredHeaderParameters example
```yaml ```yaml
swagger: '2.0' swagger: '2.0'
info: info:
@ -127,31 +128,33 @@ x-ignoredHeaderParameters:
- X-Test-Header - X-Test-Header
``` ```
### Info Object ## Info Object
Extends the OpenAPI [Info Object](https://redocly.com/docs/openapi-visual-reference/info/) Extends the OpenAPI [Info Object](https://redocly.com/docs/openapi-visual-reference/info/)
#### x-logo
| Field Name | Type | Description | ### x-logo
| Field Name | Type | Description |
| :------------- | :-----------: | :---------- | | :------------- | :-----------: | :---------- |
| x-logo | [Logo Object](#logo-object) | The information about API logo | | x-logo | [Logo Object](#logo-object) | The information about API logo |
###### How to use with Redoc #### How to use with Redoc
`x-logo` is used to specify API logo. The corresponding image is displayed just above the side-menu. `x-logo` is used to specify API logo. The corresponding image is displayed just above the side-menu.
<a name="logoObject"></a> <a name="logoObject"></a>
#### Logo Object #### Logo Object
The information about API logo The information about API logo
###### Fixed fields #### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :-------------- | :------: | :---------- | | :-------------- | :------: | :---------- |
| url | string | The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location | url | string | The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location |
| backgroundColor | string | background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) | backgroundColor | string | background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) |
| altText | string | Text to use for alt tag on the logo. Defaults to 'logo' if nothing is provided. | altText | string | Text to use for alt tag on the logo. Defaults to 'logo' if nothing is provided. |
| href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS. | href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS. |
###### x-logo example #### x-logo example
json json
```json ```json
{ {
@ -177,19 +180,19 @@ info:
altText: "Petstore logo" altText: "Petstore logo"
``` ```
### Tag Object ## Tag Object
Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/) Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/)
#### x-traitTag ### x-traitTag
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-traitTag | boolean | In Swagger two operations can have multiple tags. This property distinguishes between tags that are used to group operations (default) from tags that are used to mark operation with certain trait (`true` value) | | x-traitTag | boolean | In Swagger two operations can have multiple tags. This property distinguishes between tags that are used to group operations (default) from tags that are used to mark operation with certain trait (`true` value) |
###### How to use with Redoc #### How to use with Redoc
Tags that have `x-traitTag` set to `true` are listed in the side-menu but don't have any subitems (operations). It also renders the `description` tag. Tags that have `x-traitTag` set to `true` are listed in the side-menu but don't have any subitems (operations). It also renders the `description` tag.
This is useful for handling out common things like Pagination, Rate-Limits, etc. This is useful for handling out common things like Pagination, Rate-Limits, etc.
###### x-traitTag example #### x-traitTag example
json json
```json ```json
{ {
@ -205,36 +208,37 @@ description: Pagination description (can use markdown syntax)
x-traitTag: true x-traitTag: true
``` ```
#### x-displayName ### x-displayName
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-displayName | string | Defines the text that is used for this tag in the menu and in section headings | | x-displayName | string | Defines the text that is used for this tag in the menu and in section headings |
### Operation Object vendor extensions ## Operation Object vendor extensions
Extends the OpenAPI [Operation Object](https://redocly.com/docs/openapi-visual-reference/operation/) Extends the OpenAPI [Operation Object](https://redocly.com/docs/openapi-visual-reference/operation/)
#### x-codeSamples ### x-codeSamples
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-codeSamples | [ [Code Sample Object](#code-sample-object) ] | A list of code samples associated with operation | | x-codeSamples | [ [Code Sample Object](#code-sample-object) ] | A list of code samples associated with operation |
###### How to use with Redoc #### How to use with Redoc
`x-codeSamples` are rendered on the right panel in Redoc. `x-codeSamples` are rendered on the right panel in Redoc.
<a name="codeSampleObject"></a> <a name="codeSampleObject"></a>
#### Code Sample Object
### Code Sample Object
Operation code sample Operation code sample
###### Fixed fields #### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :---------- | :------: | :----------- | | :---------- | :------: | :----------- |
| lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) | | lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) |
| label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default | | label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default |
| source | string | Code sample source code | | source | string | Code sample source code |
###### Code Sample Object example #### Code Sample Object example
json json
```json ```json
{ {
@ -248,53 +252,53 @@ lang: JavaScript
source: console.log('Hello World'); source: console.log('Hello World');
``` ```
### Parameter Object ## Parameter Object
Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/) Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/)
#### x-examples ### x-examples
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-examples | [Example Object](https://redocly.com/docs/openapi-visual-reference/example/) | Object that contains examples for the request. Applies when `in` is `body` and mime-type is `application/json` | | x-examples | [Example Object](https://redocly.com/docs/openapi-visual-reference/example/) | Object that contains examples for the request. Applies when `in` is `body` and mime-type is `application/json` |
###### How to use with Redoc #### How to use with Redoc
`x-examples` are rendered in the JSON tab on the right panel in Redoc. `x-examples` are rendered in the JSON tab on the right panel in Redoc.
### Response Object vendor extensions ## Response Object vendor extensions
Extends the OpenAPI [Response Object](https://redocly.com/docs/openapi-visual-reference/response/). Extends the OpenAPI [Response Object](https://redocly.com/docs/openapi-visual-reference/response/).
#### x-summary ### x-summary
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-summary | string | a short summary of the response | | x-summary | string | a short summary of the response |
###### How to use with Redoc #### How to use with Redoc
If specified, you can use `x-summary` as the response button text, with description rendered under the button. If specified, you can use `x-summary` as the response button text, with description rendered under the button.
### Schema Object ## Schema Object
Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/) Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/)
#### x-nullable ### x-nullable
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-nullable | boolean | marks schema as a nullable | | x-nullable | boolean | marks schema as a nullable |
###### How to use with Redoc #### How to use with Redoc
Schemas marked as `x-nullable` are marked in Redoc with the label Nullable. Schemas marked as `x-nullable` are marked in Redoc with the label Nullable.
#### x-extendedDiscriminator ### x-extendedDiscriminator
**ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools. **ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools.
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-extendedDiscriminator | string | specifies extended discriminator | | x-extendedDiscriminator | string | specifies extended discriminator |
###### How to use with Redoc #### How to use with Redoc
Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`. Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
Value of this field specifies the field which is used as an extended discriminator. Value of this field specifies the field which is used as an extended discriminator.
Redoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field. Redoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field.
Redoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`. Redoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`.
###### x-extendedDiscriminator example #### x-extendedDiscriminator example
```yaml ```yaml
@ -334,19 +338,19 @@ PayPalPayment:
In the example above, the names of definitions (`PayPalPayment`) are named differently than names in the payload (`paypal`) which is not supported by default `discriminator`. In the example above, the names of definitions (`PayPalPayment`) are named differently than names in the payload (`paypal`) which is not supported by default `discriminator`.
#### x-additionalPropertiesName ### x-additionalPropertiesName
**ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools. **Attention**: This is a Redoc-specific vendor extension, and is not supported by other tools.
Extends the `additionalProperties` property of the schema object. Extends the `additionalProperties` property of the schema object.
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-additionalPropertiesName | string | descriptive name of additional properties keys | | x-additionalPropertiesName | string | descriptive name of additional properties keys |
###### How to use with Redoc #### How to use with Redoc
Redoc uses this extension to display a more descriptive property name in objects with `additionalProperties` when viewing the property list with an `object`. Redoc uses this extension to display a more descriptive property name in objects with `additionalProperties` when viewing the property list with an `object`.
###### x-additionalPropertiesName example #### x-additionalPropertiesName example
```yaml ```yaml
Player: Player:
@ -362,20 +366,20 @@ Player:
type: string type: string
``` ```
#### x-explicitMappingOnly ### x-explicitMappingOnly
**ATTENTION**: This is Redoc-specific vendor extension, and is not supported by other tools. **Attention**: This is Redoc-specific vendor extension, and is not supported by other tools.
Extends the `discriminator` property of the schema object. Extends the `discriminator` property of the schema object.
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only | | x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only |
###### How to use with Redoc #### How to use with Redoc
Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker. Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
When set to `true`, the selectpicker lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown. When set to `true`, the selectpicker lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown.
###### x-explicitMappingOnly example #### x-explicitMappingOnly example
```yaml ```yaml

4
docs/security-definitions-injection.md
View File

@ -4,7 +4,7 @@ You can inject the Security Definitions widget anywhere in your specification `d
```markdown ```markdown
... ...
# Authorization ## Authorization
Some description Some description
@ -14,7 +14,7 @@ Some description
The inject instruction is wrapped in an HTML comment, The inject instruction is wrapped in an HTML comment,
so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI. so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI.
# Default behavior ## Default behavior
If the injection tag is not found in the description, it is appended to the end If the injection tag is not found in the description, it is appended to the end
of description under the `Authentication` header. of description under the `Authentication` header.