diff --git a/.github/styles/Vocab/Rules/accept.txt b/.github/styles/config/vocabularies/Rules/accept.txt similarity index 100% rename from .github/styles/Vocab/Rules/accept.txt rename to .github/styles/config/vocabularies/Rules/accept.txt diff --git a/.github/styles/Vocab/Rules/reject.txt b/.github/styles/config/vocabularies/Rules/reject.txt similarity index 100% rename from .github/styles/Vocab/Rules/reject.txt rename to .github/styles/config/vocabularies/Rules/reject.txt diff --git a/.github/workflows/docs-tests.yaml b/.github/workflows/docs-tests.yaml new file mode 100644 index 00000000..66729455 --- /dev/null +++ b/.github/workflows/docs-tests.yaml @@ -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 diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml deleted file mode 100644 index c5220c41..00000000 --- a/.github/workflows/vale.yaml +++ /dev/null @@ -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}} diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..ab1a86e5 --- /dev/null +++ b/.markdownlint.yaml @@ -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 diff --git a/.mlc.toml b/.mlc.toml new file mode 100644 index 00000000..46b37072 --- /dev/null +++ b/.mlc.toml @@ -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" diff --git a/README.md b/README.md index 8eca400f..68e2b3e6 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@
Redoc logo - # 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) - [![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)
@@ -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)
- ![](docs/images/code-samples-demo.gif) + ![code samples in action](docs/images/code-samples-demo.gif) ## 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 `` 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_ diff --git a/demo/index.html b/demo/index.html index 8675b407..8d751a6b 100644 --- a/demo/index.html +++ b/demo/index.html @@ -1,46 +1,63 @@ + + + Redoc Interactive Demo + + - - - ReDoc Interactive Demo - - + + + + - - - - + + + - redoc { - display: block; - } - - - + +
- -
+ - - - \ No newline at end of file + if (window.location.host === 'rebilly.github.io') { + ga('create', 'UA-81703547-1', 'auto'); + ga('send', 'pageview'); + } + + + diff --git a/demo/index.tsx b/demo/index.tsx index 048aea86..2c0e3359 100644 --- a/demo/index.tsx +++ b/demo/index.tsx @@ -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; } diff --git a/demo/museum-logo.png b/demo/museum-logo.png new file mode 100644 index 00000000..c613d991 Binary files /dev/null and b/demo/museum-logo.png differ diff --git a/demo/museum.yaml b/demo/museum.yaml new file mode 100644 index 00000000..4d6f55e0 --- /dev/null +++ b/demo/museum.yaml @@ -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: [] diff --git a/demo/playground/hmr-playground.tsx b/demo/playground/hmr-playground.tsx index efd843ab..10c417e2 100644 --- a/demo/playground/hmr-playground.tsx +++ b/demo/playground/hmr-playground.tsx @@ -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 }; diff --git a/demo/playground/index.html b/demo/playground/index.html index d322ee3e..bfc9589b 100644 --- a/demo/playground/index.html +++ b/demo/playground/index.html @@ -1,25 +1,26 @@ + + + + Redoc + + + - redoc { - display: block; - } - - - - - - - - - \ No newline at end of file + + + + diff --git a/demo/webpack.config.ts b/demo/webpack.config.ts index cf66c749..1f7d8408 100644 --- a/demo/webpack.config.ts +++ b/demo/webpack.config.ts @@ -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'], }), ], }); diff --git a/docs/config.md b/docs/config.md index 36880135..28e24f7e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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). +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 diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index 2a4c7198..74ddbd23 100644 --- a/docs/deployment/cli.md +++ b/docs/deployment/cli.md @@ -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 diff --git a/docs/deployment/html.md b/docs/deployment/html.md index fab2169c..23b914b2 100644 --- a/docs/deployment/html.md +++ b/docs/deployment/html.md @@ -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 ``` diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md index a824a66c..02aa5344 100644 --- a/docs/deployment/intro.md +++ b/docs/deployment/intro.md @@ -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) diff --git a/docs/index.md b/docs/index.md index 58613ee6..a98776c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 ``` diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index d6280adc..8ee7d5c9 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -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! + #### 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. + #### 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. -#### 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 diff --git a/docs/security-definitions-injection.md b/docs/security-definitions-injection.md index ded59881..dbe3d6b6 100644 --- a/docs/security-definitions-injection.md +++ b/docs/security-definitions-injection.md @@ -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.