mirror of
https://github.com/Redocly/redoc.git
synced 2025-08-01 19:00:21 +03:00
Merge branch 'main' into chore/fix-vulnerabilities-and-update-libs
This commit is contained in:
Alex Varchuk
commit
ffd5cdd449
37
.github/workflows/docs-tests.yaml
vendored
Normal file
37
.github/workflows/docs-tests.yaml
vendored
Normal 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
16
.github/workflows/vale.yaml
vendored
|
|
@ -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
54
.markdownlint.yaml
Normal 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
4
.mlc.toml
Normal 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
15
README.md
|
|
@ -1,11 +1,11 @@
|
|||
<div align="center">
|
||||
<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
|
||||
|
||||
[](https://www.npmjs.com/package/redoc) [](https://github.com/Redocly/redoc/blob/main/LICENSE)
|
||||
|
||||
[](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc)
|
||||
[](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc)
|
||||
</div>
|
||||
|
||||
|
||||
|
|
@ -34,13 +34,11 @@ enter the URL for your definition and select **TRY IT**.
|
|||
|
||||
- Responsive three-panel design with menu/scrolling synchronization
|
||||
- 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
|
||||
- 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/)
|
||||
- Code samples support (with vendor extension) <br>
|
||||
|
||||
|
||||
|
||||
## 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`:
|
||||
|
||||
```
|
||||
```bash
|
||||
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
|
||||
|
||||
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?
|
||||
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/)
|
||||
- [APIs.guru](https://apis.guru/api-doc/)
|
||||
- [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_
|
||||
|
||||
|
|
|
|||
|
|
@ -1,46 +1,63 @@
|
|||
<!DOCTYPE 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 charset="UTF-8" />
|
||||
<title>ReDoc Interactive Demo</title>
|
||||
<meta name="description" content="ReDoc Interactive Demo. OpenAPI/Swagger-generated API Reference Documentation" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta property="og:title" content="Redoc Interactive Demo" />
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Redoc Interactive Demo. OpenAPI-generated API Reference Documentation"
|
||||
/>
|
||||
<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">
|
||||
<meta property="og:description" content="ReDoc Interactive Demo. OpenAPI/Swagger-generated API Reference Documentation">
|
||||
<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">
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
redoc {
|
||||
display: block;
|
||||
}
|
||||
</style>
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
|
||||
rel="stylesheet"
|
||||
/>
|
||||
</head>
|
||||
|
||||
redoc {
|
||||
display: block;
|
||||
}
|
||||
</style>
|
||||
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
|
||||
</head>
|
||||
<body>
|
||||
<div id="container"></div>
|
||||
|
||||
<body>
|
||||
<div id="container"> </div>
|
||||
|
||||
<script>
|
||||
(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');
|
||||
|
||||
if (window.location.host === 'rebilly.github.io') {
|
||||
ga('create', 'UA-81703547-1', 'auto');
|
||||
ga('send', 'pageview');
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
<script>
|
||||
(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');
|
||||
|
||||
if (window.location.host === 'rebilly.github.io') {
|
||||
ga('create', 'UA-81703547-1', 'auto');
|
||||
ga('send', 'pageview');
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -5,11 +5,12 @@ import { RedocStandalone } from '../src';
|
|||
import ComboBox from './ComboBox';
|
||||
import FileInput from './components/FileInput';
|
||||
|
||||
const DEFAULT_SPEC = 'openapi.yaml';
|
||||
const NEW_VERSION_SPEC = 'openapi-3-1.yaml';
|
||||
const DEFAULT_SPEC = 'museum.yaml';
|
||||
const NEW_VERSION_PETSTORE = 'openapi-3-1.yaml';
|
||||
|
||||
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/googleapis.com/calendar/v3/openapi.yaml',
|
||||
|
|
@ -54,7 +55,7 @@ class DemoApp extends React.Component<
|
|||
};
|
||||
|
||||
handleChange = (url: string) => {
|
||||
if (url === NEW_VERSION_SPEC) {
|
||||
if (url === NEW_VERSION_PETSTORE) {
|
||||
this.setState({ cors: false });
|
||||
0;
|
||||
}
|
||||
|
|
|
|||
BIN
demo/museum-logo.png
Normal file
BIN
demo/museum-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.5 KiB |
772
demo/museum.yaml
Normal file
772
demo/museum.yaml
Normal 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: []
|
||||
|
|
@ -9,7 +9,7 @@ const swagger = window.location.search.indexOf('swagger') > -1;
|
|||
const userUrl = window.location.search.match(/url=(.*)$/);
|
||||
|
||||
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 };
|
||||
|
||||
|
|
|
|||
|
|
@ -1,25 +1,26 @@
|
|||
<!DOCTYPE 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>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>ReDoc</title>
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
redoc {
|
||||
display: block;
|
||||
}
|
||||
</style>
|
||||
<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>
|
||||
redoc {
|
||||
display: block;
|
||||
}
|
||||
</style>
|
||||
<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>
|
||||
|
|
@ -121,7 +121,7 @@ export default (env: { playground?: boolean; bench?: boolean } = {}, { mode }) =
|
|||
webpackIgnore(/json-schema-ref-parser\/lib\/dereference\.js/),
|
||||
webpackIgnore(/^\.\/SearchWorker\.worker$/),
|
||||
new CopyWebpackPlugin({
|
||||
patterns: ['demo/openapi.yaml'],
|
||||
patterns: ['demo/museum.yaml'],
|
||||
}),
|
||||
],
|
||||
});
|
||||
|
|
|
|||
|
|
@ -6,12 +6,12 @@ Each deployment type has documentation on how to configure options for that type
|
|||
|
||||
**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).
|
||||
For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`.
|
||||
|
||||
:::
|
||||
{% /admonition %}
|
||||
|
||||
## Functional settings
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
||||
```
|
||||
```sh
|
||||
npm install redoc
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
- OpenAPI 3.0
|
||||
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml)
|
||||
- [Swagger Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json)
|
||||
- [Museum Example API](https://github.com/Redocly/museum-openapi-example/blob/main/openapi.yaml)
|
||||
- [Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json)
|
||||
- OpenAPI 2.0
|
||||
- [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)
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
||||
```
|
||||
```sh
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
redocly preview-docs openapi.yaml
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -3,78 +3,79 @@
|
|||
You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc.
|
||||
|
||||
- [Redoc vendor extensions](#redoc-vendor-extensions)
|
||||
- [Swagger Object](#swagger-object)
|
||||
- [x-servers](#x-servers)
|
||||
- [x-tagGroups](#x-taggroups)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc)
|
||||
- [Tag Group Object](#tag-group-object)
|
||||
- [Fixed fields](#fixed-fields)
|
||||
- [x-tagGroups example](#x-taggroups-example)
|
||||
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-1)
|
||||
- [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example)
|
||||
- [Info Object](#info-object)
|
||||
- [x-logo](#x-logo)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-2)
|
||||
- [Logo Object](#logo-object)
|
||||
- [Fixed fields](#fixed-fields-1)
|
||||
- [x-logo example](#x-logo-example)
|
||||
- [Tag Object](#tag-object)
|
||||
- [x-traitTag](#x-traittag)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-3)
|
||||
- [x-traitTag example](#x-traittag-example)
|
||||
- [x-displayName](#x-displayname)
|
||||
- [Operation Object vendor extensions](#operation-object-vendor-extensions)
|
||||
- [x-codeSamples](#x-codesamples)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-4)
|
||||
- [Code Sample Object](#code-sample-object)
|
||||
- [Fixed fields](#fixed-fields-2)
|
||||
- [Code Sample Object example](#code-sample-object-example)
|
||||
- [Parameter Object](#parameter-object)
|
||||
- [x-examples](#x-examples)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-5)
|
||||
- [Response Object vendor extensions](#response-object-vendor-extensions)
|
||||
- [x-summary](#x-summary)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-6)
|
||||
- [Schema Object](#schema-object)
|
||||
- [x-nullable](#x-nullable)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-7)
|
||||
- [x-extendedDiscriminator](#x-extendeddiscriminator)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-8)
|
||||
- [x-extendedDiscriminator example](#x-extendeddiscriminator-example)
|
||||
- [x-additionalPropertiesName](#x-additionalpropertiesname)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-9)
|
||||
- [x-additionalPropertiesName example](#x-additionalpropertiesname-example)
|
||||
- [x-explicitMappingOnly](#x-explicitmappingonly)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-10)
|
||||
- [x-explicitMappingOnly example](#x-explicitmappingonly-example)
|
||||
- [Swagger Object](#swagger-object)
|
||||
- [x-servers](#x-servers)
|
||||
- [x-tagGroups](#x-taggroups)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc)
|
||||
- [Tag Group Object](#tag-group-object)
|
||||
- [Fixed fields](#fixed-fields)
|
||||
- [x-tagGroups example](#x-taggroups-example)
|
||||
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-1)
|
||||
- [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example)
|
||||
- [Info Object](#info-object)
|
||||
- [x-logo](#x-logo)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-2)
|
||||
- [Logo Object](#logo-object)
|
||||
- [Fixed fields](#fixed-fields-1)
|
||||
- [x-logo example](#x-logo-example)
|
||||
- [Tag Object](#tag-object)
|
||||
- [x-traitTag](#x-traittag)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-3)
|
||||
- [x-traitTag example](#x-traittag-example)
|
||||
- [x-displayName](#x-displayname)
|
||||
- [Operation Object vendor extensions](#operation-object-vendor-extensions)
|
||||
- [x-codeSamples](#x-codesamples)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-4)
|
||||
- [Code Sample Object](#code-sample-object)
|
||||
- [Fixed fields](#fixed-fields-2)
|
||||
- [Code Sample Object example](#code-sample-object-example)
|
||||
- [Parameter Object](#parameter-object)
|
||||
- [x-examples](#x-examples)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-5)
|
||||
- [Response Object vendor extensions](#response-object-vendor-extensions)
|
||||
- [x-summary](#x-summary)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-6)
|
||||
- [Schema Object](#schema-object)
|
||||
- [x-nullable](#x-nullable)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-7)
|
||||
- [x-extendedDiscriminator](#x-extendeddiscriminator)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-8)
|
||||
- [x-extendedDiscriminator example](#x-extendeddiscriminator-example)
|
||||
- [x-additionalPropertiesName](#x-additionalpropertiesname)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-9)
|
||||
- [x-additionalPropertiesName example](#x-additionalpropertiesname-example)
|
||||
- [x-explicitMappingOnly](#x-explicitmappingonly)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-10)
|
||||
- [x-explicitMappingOnly example](#x-explicitmappingonly-example)
|
||||
|
||||
### Swagger Object
|
||||
Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/)
|
||||
## Swagger Object
|
||||
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.
|
||||
|
||||
#### 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 |
|
||||
|
||||
###### How to use with Redoc
|
||||
#### How to use with Redoc
|
||||
`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!
|
||||
|
||||
<a name="tagGroupObject"></a>
|
||||
|
||||
#### Tag Group Object
|
||||
Information about tags group
|
||||
###### Fixed fields
|
||||
| Field Name | Type | Description |
|
||||
##### Fixed fields
|
||||
| Field Name | Type | Description |
|
||||
| :---------- | :--------: | :---------- |
|
||||
| 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
|
||||
{
|
||||
|
|
@ -104,18 +105,18 @@ x-tagGroups:
|
|||
- Secondary Stats
|
||||
```
|
||||
|
||||
#### x-ignoredHeaderParameters
|
||||
### x-ignoredHeaderParameters
|
||||
|
||||
|
||||
| Field Name | Type | Description |
|
||||
| Field Name | Type | Description |
|
||||
| :-------------------------- | :-----------: | :---------- |
|
||||
| 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.
|
||||
|
||||
###### x-ignoredHeaderParameters example
|
||||
#### x-ignoredHeaderParameters example
|
||||
```yaml
|
||||
swagger: '2.0'
|
||||
info:
|
||||
|
|
@ -127,31 +128,33 @@ x-ignoredHeaderParameters:
|
|||
- X-Test-Header
|
||||
```
|
||||
|
||||
### Info Object
|
||||
## Info Object
|
||||
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 |
|
||||
|
||||
###### 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.
|
||||
|
||||
<a name="logoObject"></a>
|
||||
|
||||
#### Logo Object
|
||||
The information about API logo
|
||||
|
||||
###### Fixed fields
|
||||
| Field Name | Type | Description |
|
||||
#### Fixed fields
|
||||
| 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
|
||||
| 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.
|
||||
| href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS.
|
||||
| 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) |
|
||||
| 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. |
|
||||
|
||||
|
||||
###### x-logo example
|
||||
#### x-logo example
|
||||
json
|
||||
```json
|
||||
{
|
||||
|
|
@ -177,19 +180,19 @@ info:
|
|||
altText: "Petstore logo"
|
||||
```
|
||||
|
||||
### Tag Object
|
||||
## Tag Object
|
||||
Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/)
|
||||
|
||||
#### x-traitTag
|
||||
| Field Name | Type | Description |
|
||||
### x-traitTag
|
||||
| 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) |
|
||||
|
||||
###### 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.
|
||||
This is useful for handling out common things like Pagination, Rate-Limits, etc.
|
||||
|
||||
###### x-traitTag example
|
||||
#### x-traitTag example
|
||||
json
|
||||
```json
|
||||
{
|
||||
|
|
@ -205,36 +208,37 @@ description: Pagination description (can use markdown syntax)
|
|||
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 |
|
||||
|
||||
### Operation Object vendor extensions
|
||||
## Operation Object vendor extensions
|
||||
Extends the OpenAPI [Operation Object](https://redocly.com/docs/openapi-visual-reference/operation/)
|
||||
|
||||
#### x-codeSamples
|
||||
| Field Name | Type | Description |
|
||||
### x-codeSamples
|
||||
| Field Name | Type | Description |
|
||||
| :------------- | :------: | :---------- |
|
||||
| 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.
|
||||
|
||||
<a name="codeSampleObject"></a>
|
||||
#### Code Sample Object
|
||||
|
||||
### Code Sample Object
|
||||
Operation code sample
|
||||
|
||||
###### Fixed fields
|
||||
| Field Name | Type | Description |
|
||||
#### Fixed fields
|
||||
| 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) |
|
||||
| label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default |
|
||||
| source | string | Code sample source code |
|
||||
|
||||
|
||||
###### Code Sample Object example
|
||||
#### Code Sample Object example
|
||||
json
|
||||
```json
|
||||
{
|
||||
|
|
@ -248,53 +252,53 @@ lang: JavaScript
|
|||
source: console.log('Hello World');
|
||||
```
|
||||
|
||||
### Parameter Object
|
||||
## Parameter Object
|
||||
Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/)
|
||||
|
||||
#### x-examples
|
||||
### x-examples
|
||||
| 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` |
|
||||
|
||||
###### How to use with Redoc
|
||||
#### How to use with 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/).
|
||||
|
||||
#### x-summary
|
||||
| Field Name | Type | Description |
|
||||
### x-summary
|
||||
| Field Name | Type | Description |
|
||||
| :------------- | :------: | :---------- |
|
||||
| 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.
|
||||
|
||||
### Schema Object
|
||||
## Schema Object
|
||||
Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/)
|
||||
|
||||
#### x-nullable
|
||||
| Field Name | Type | Description |
|
||||
### x-nullable
|
||||
| Field Name | Type | Description |
|
||||
| :------------- | :------: | :---------- |
|
||||
| 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.
|
||||
|
||||
#### x-extendedDiscriminator
|
||||
### x-extendedDiscriminator
|
||||
**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 |
|
||||
|
||||
###### How to use with Redoc
|
||||
#### How to use with Redoc
|
||||
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.
|
||||
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`.
|
||||
|
||||
###### x-extendedDiscriminator example
|
||||
#### x-extendedDiscriminator example
|
||||
|
||||
```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`.
|
||||
|
||||
#### x-additionalPropertiesName
|
||||
**ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools.
|
||||
### x-additionalPropertiesName
|
||||
**Attention**: This is a Redoc-specific vendor extension, and is not supported by other tools.
|
||||
|
||||
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 |
|
||||
|
||||
###### 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`.
|
||||
|
||||
###### x-additionalPropertiesName example
|
||||
#### x-additionalPropertiesName example
|
||||
|
||||
```yaml
|
||||
Player:
|
||||
|
|
@ -362,20 +366,20 @@ Player:
|
|||
type: string
|
||||
```
|
||||
|
||||
#### x-explicitMappingOnly
|
||||
**ATTENTION**: This is Redoc-specific vendor extension, and is not supported by other tools.
|
||||
### x-explicitMappingOnly
|
||||
**Attention**: This is Redoc-specific vendor extension, and is not supported by other tools.
|
||||
|
||||
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 |
|
||||
|
||||
###### How to use with Redoc
|
||||
#### How to use with Redoc
|
||||
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.
|
||||
|
||||
###### x-explicitMappingOnly example
|
||||
#### x-explicitMappingOnly example
|
||||
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ You can inject the Security Definitions widget anywhere in your specification `d
|
|||
|
||||
```markdown
|
||||
...
|
||||
# Authorization
|
||||
## Authorization
|
||||
|
||||
Some description
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ Some description
|
|||
The inject instruction is wrapped in an HTML comment,
|
||||
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
|
||||
of description under the `Authentication` header.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user