From 7b2931dc91e6bfefb909d12d512aeb1d0df29a19 Mon Sep 17 00:00:00 2001 From: redocly-bot Date: Thu, 9 Nov 2023 15:56:30 +0000 Subject: [PATCH 1/9] sync: Synced local 'docs/' with remote 'docs/redoc/' --- docs/config.md | 2 +- docs/deployment/html.md | 2 +- docs/index.md | 4 +- docs/redoc-vendor-extensions.md | 212 +++++++++++++------------ docs/security-definitions-injection.md | 4 +- 5 files changed, 114 insertions(+), 110 deletions(-) diff --git a/docs/config.md b/docs/config.md index 36880135..b034ed6e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -8,7 +8,7 @@ Each deployment type has documentation on how to configure options for that type :::success 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`. ::: 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/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..5074cff3 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 +## Swagger Object Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) -#### 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 -###### 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,23 +128,25 @@ 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) @@ -151,7 +154,7 @@ The information about API logo | 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. From 8c04c02ab02dadacb3fcaf4c02e56ed2b5839b88 Mon Sep 17 00:00:00 2001 From: Adam Altman Date: Mon, 13 Nov 2023 04:16:32 -0600 Subject: [PATCH 2/9] docs: fix admonition on config page (#2452) --- docs/config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config.md b/docs/config.md index b034ed6e..9a668892 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). For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. -::: +{% /admonition %} ## Functional settings From e9f9799e8901d8640abae0cff74ec763d71d7957 Mon Sep 17 00:00:00 2001 From: Alexei Maridashvili Date: Mon, 13 Nov 2023 12:48:58 +0100 Subject: [PATCH 3/9] Update README.md (#2422) Fix link to deployment options --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8eca400f..731253a6 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ 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 From 0db1e9872de108a7c49c13f5773bcc4207ad4f98 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 1 Dec 2023 16:00:50 +0000 Subject: [PATCH 4/9] docs: Remove references to interactive docs in the open source project (#2460) * docs: Remove references to interactive docs in the open source project * Update README.md Co-authored-by: Adam Altman --------- Co-authored-by: Adam Altman --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 731253a6..d555b218 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@
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) @@ -34,8 +34,6 @@ 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/) @@ -75,7 +73,7 @@ Add your own `spec-url` to the `` tag; this attribute can also be a local 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/) From 21b961dffabc9cc1e6e56cfb8d1de0e9cf83d94b Mon Sep 17 00:00:00 2001 From: Javi Rubio Date: Thu, 28 Dec 2023 16:38:40 +0100 Subject: [PATCH 5/9] Add Quaderno API to README's Showcase section (#2468) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index d555b218..8a06f76e 100644 --- a/README.md +++ b/README.md @@ -102,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_ From 76cecf054cec9ab68ab25ef941c30946ba0fcee3 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 17 Jan 2024 18:33:40 +0000 Subject: [PATCH 6/9] chore: Update directory structure for Vale v3 (#2477) * chore: Update directory structure for Vale v3 * chore: update Vale folder name --- .github/styles/{Vocab => config/vocabularies}/Rules/accept.txt | 0 .github/styles/{Vocab => config/vocabularies}/Rules/reject.txt | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename .github/styles/{Vocab => config/vocabularies}/Rules/accept.txt (100%) rename .github/styles/{Vocab => config/vocabularies}/Rules/reject.txt (100%) 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 From 4fd22f6d74a7709c318d78005354e66b0afbc2b7 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 29 Jan 2024 16:39:44 +0000 Subject: [PATCH 7/9] docs: Add docs tooling to align with publishing to main site (#2484) * docs: add markdownlint and some link checks alongside vale * docs: add link checker config and fix/update some links reported broken * docs: update markdownlint action * docs: fix markdown table formatting * docs: Unpin Vale version and pick up the latest --- .github/workflows/docs-tests.yaml | 37 +++++++++++++++++++++ .github/workflows/vale.yaml | 16 --------- .markdownlint.yaml | 54 +++++++++++++++++++++++++++++++ .mlc.toml | 4 +++ README.md | 8 ++--- docs/config.md | 2 +- docs/deployment/cli.md | 4 +-- docs/deployment/intro.md | 4 +-- docs/redoc-vendor-extensions.md | 12 +++---- 9 files changed, 110 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/docs-tests.yaml delete mode 100644 .github/workflows/vale.yaml create mode 100644 .markdownlint.yaml create mode 100644 .mlc.toml 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 8a06f76e..68e2b3e6 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@
Redoc logo - # Generate beautiful API documentation from OpenAPI +# 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)
@@ -38,7 +38,7 @@ enter the URL for your definition and select **TRY IT**. - 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 @@ -48,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 ``` diff --git a/docs/config.md b/docs/config.md index 9a668892..28e24f7e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -6,7 +6,7 @@ Each deployment type has documentation on how to configure options for that type **Versions: 2.x** -{% admonition type="success" name="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`. diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index 2a4c7198..8726248b 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](../../installation.md#use-npx-at-runtime) using npx or Docker. ## Step 2 - Build the HTML file 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/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 5074cff3..8ee7d5c9 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -50,7 +50,7 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v - [x-explicitMappingOnly example](#x-explicitmappingonly-example) ## Swagger Object -Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) +Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi-1/) ### x-servers 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. @@ -73,7 +73,7 @@ Information about tags group | 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 json @@ -148,10 +148,10 @@ The information about API logo #### 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 From 8c391497bf5b8445251cb55f8705f54bfbfdad80 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 12 Feb 2024 14:44:00 +0000 Subject: [PATCH 8/9] docs: Fix a link that couldn't be checked as it reaches outside the Redoc project (#2490) --- docs/deployment/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index 8726248b..74ddbd23 100644 --- a/docs/deployment/cli.md +++ b/docs/deployment/cli.md @@ -14,7 +14,7 @@ First, you need to install the `@redocly/cli` package. You can install it [globally](../../cli/installation.md#install-globally) using npm or Yarn. -Or you can install it during [runtime](../../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 From 3f3f9551ee36f8743a65d774f5212a34dea1affc Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 2 Apr 2024 16:16:44 +0100 Subject: [PATCH 9/9] docs: Update API examples list to include Museum API (#2506) * feat: Update API examples list to include Museum API * updates museum.yaml with logo and replaces petstore with museum api in playground for local dev and some minor edits to redoc name * docs: update definition --------- Co-authored-by: Heather Cloward Co-authored-by: Alex Varchuk --- demo/index.html | 93 ++-- demo/index.tsx | 9 +- demo/museum-logo.png | Bin 0 -> 2601 bytes demo/museum.yaml | 772 +++++++++++++++++++++++++++++ demo/playground/hmr-playground.tsx | 2 +- demo/playground/index.html | 43 +- demo/webpack.config.ts | 2 +- 7 files changed, 856 insertions(+), 65 deletions(-) create mode 100644 demo/museum-logo.png create mode 100644 demo/museum.yaml 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 0000000000000000000000000000000000000000..c613d99183d63ad5f46e7902231c03e14e22652e GIT binary patch literal 2601 zcmV+^3fA?BP)v5fO=riOb8&?Ck85laotJON4}kJUl#JUS1&~AvQKPsi~<(Mn;B)hI)E> zARr)FSy?D3C>R(RV`F0s3=BX(K%J|>4FCWMV@X6oRCt{2U3*_5F${D?d4s$K(G&EP z)9?QQ56{PuWTq5L*}dOo{*6_#r@=PR)`Jc5AK?PM@skbj-S^?w z<2in_-0~Yc4y#(p{_jDr|I2#){PFxXcK$Ydw{MToWLG!HHVE%!*82FgC;mSE{A(Xf z`Ng=3tghX(o{D6*kRSEFK7enfyMDD;U2A6F8*iCm7s_I=`x(qEcm3X3HPD*L6{2sn`4B3m1Fshcj>=@*_VY5N#>et0)R0CO(RpA?CV$QRgE(@P^Nm=u!O} z;xzg@h}31`0-fcHz14Jf(9eJH@wM3@U#hJ@N;r%odZ$YP?1NFWS54G+MD}bgp;4*zbQ{^X>Ah z$rg**43v^@NKTV$eBCM`v0#4Ke}|GWO`OAV*#YduC^14^)>RLK{Xv9Lb^v>kEVGVB zck9<@P@0yHmzS66^haud8ogRFuHJF}hTay(cG2;lW8Ua|ps|Na#9G!nI|vcYTI!xv-w3jF$?c>>lr2IzGodUX9pYngF6;vDNU8Q`i%|L<%3iV{=VKw2aIjkQ38_J6 zYif{whtw{q0rIh^3A+uypj<@ACh*IF3`tQ^!sqJRT-XIjgj@y6woW4lavZRfs}6j& z>oP)~1*9H!xF8vcwYW{FxR&}OpY4XQ3%o&Oftqb;Sc=c9fTdit=Mkz^MV?lQ$O|Sy zK6~AOrF4kTwp@@3(4-SZD4)GWz*0KI$Ksn2CaX^j^4VK*L)je^7z-s<(mbbDkS9rD za45f<+)_Ej*P3LtQnZ+z$||A9Ck2vXg``;J5T9+ybPKxBqAqyQ^4tMXGjqo+Rhr{n z32H@&W&w4JzY^w$#N|Rc#LzV{R z_bsYEh78fllm@r9t@}sOD6Q*F80ijZj@MAa^7|QLKRCr4l)>`&4HYr3UJP ze8|$EoA0=#UUj5~s?CDtxq-Ah`f|(%)IbIz9K>3xCV>ZLw~D=B8sa02c1YRLEYOX; zU>fwy@Om}cA!SEt(j@kRY0!T2NDK5k=x&Uqr&wd?GPIaRWk5*)o z+i=B8Te8{KOqXVIZMRAcCGs|0@zR!TwoPv*%jB^`mI!?tu6V`Hw&wCI3-q*ICP`S| zhE@XS+LDch=JJdP*0fz7Nmx@Xt_NwVLbWkn6tO&4*LHaXQ{y+)gG^&Fs~Jp$gz6e* zkVj5514-pX;}8>%bv?#1xyhTf%u0fp8OoD8+LBd8x>{kG+*~lAw+6P9AX?|`li|INAjFu27x}!1elqj9LqSwX4`DFC3(&;gFKS3 z@tcZmCXq9Fe60;ho-=tfk0flj&#=}B;}Dx|v$K#yXtGM49$GE)au#VEVlA&`J2T1T zCadI;6Yb2f2(3dTLbLOa5J9{7FiV%Pof)QhS%=8;Y|aZIM9}V_%MziT877#TL{7%S zlngA-*|Q|FoYG?lk_o2PAv_kQ24RA!-6NkxFtvU&J;)xpfNKU*t*|_2kEq~!djjl0 zGCjy1Yk|dM8zG^(cE5TSInnO@XL^uz2+y{u$5xzWtvC0pbW9E+dU4rT$PFtZ^`1DY9JX(NXq-vo9rLck1i2sLPCaHS2% z7#<5?2gNq4@@47!vVt(H($J72t^zm&UUfz1HD(ZMkl(mUL&xKxu|OFX(j;^kT?QEg zo!o}2G&JOBEZ{j}=z{1#*bGJfYSh#i;oEe9C3;Hh)~*TPGz(x?fpf4Oj?<&ns1}YN zA$swZiQ`9z4x%j+9-&A0KSo$~L>kABuwF47KSGD2qUfwIs*ZIUe?tOW)sR*xdW2Pg zN9Yk&A88R@Z!W8jO}0Z69gdQ5p8hWoPL9LYOwmG9)p1xepGR0lc!VBd_2Cgpphf$t za^~9100000 LNkvXXu0mjfY$N8t literal 0 HcmV?d00001 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'], }), ], });