mirror of
https://github.com/Redocly/redoc.git
synced 2024-09-20 18:58:57 +03:00
Config docs and README refresh (#2393)
* docs: Give Redoc a landing page with overview and tldr instructions * docs: move config to dedicated page * docs: modernise README, link to resources * docs: more detailed format for theme configurations * fix: README formatting * fix: Fix future tense errors and add exceptions for config fields as headings * Apply suggestions from code review Co-authored-by: Heather Cloward <heathercloward@gmail.com> * docs: minor updates from excellent pull request feedback * docs: Remove the old quickstart, update HTML as the preferred onboarding method and improve docs/examples on that page * Apply suggestions from code review Co-authored-by: Heather Cloward <heathercloward@gmail.com> --------- Co-authored-by: Heather Cloward <heathercloward@gmail.com>
This commit is contained in:
Lorna Jane Mitchell
GitHub
parent
26674e70c6
commit
b3503f2109
4
.github/styles/Rules/HeaderGerunds.yml
vendored
4
.github/styles/Rules/HeaderGerunds.yml
vendored
|
|
@ -5,3 +5,7 @@ level: error
|
|||
scope: heading
|
||||
tokens:
|
||||
- '^\w*ing.*'
|
||||
exceptions:
|
||||
- expandSingleSchemaField
|
||||
- hideLoading
|
||||
- hideSingleRequestSampleTab
|
||||
|
|
|
|||
334
README.md
334
README.md
|
|
@ -3,17 +3,15 @@
|
|||
|
||||
# Generate interactive API documentation from OpenAPI definitions
|
||||
|
||||
[](https://coveralls.io/github/Redocly/redoc?branch=main) [](https://www.npmjs.com/package/redoc) [](https://github.com/Redocly/redoc/blob/main/LICENSE)
|
||||
[](https://www.npmjs.com/package/redoc) [](https://github.com/Redocly/redoc/blob/main/LICENSE)
|
||||
|
||||
[](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc) [](https://hub.docker.com/r/redocly/redoc/)
|
||||
[](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [](https://www.npmjs.com/package/redoc) [](https://www.jsdelivr.com/package/npm/redoc)
|
||||
</div>
|
||||
|
||||
**This is the README for the `2.x` version of Redoc (React-based).**
|
||||
**The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch.**
|
||||
|
||||
## About Redoc
|
||||
|
||||
Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions.
|
||||
Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.
|
||||
|
||||
By default Redoc offers a three-panel, responsive layout:
|
||||
|
||||
|
|
@ -32,95 +30,73 @@ A version of the Swagger Petstore API is displayed by default.
|
|||
To test it with your own OpenAPI definition,
|
||||
enter the URL for your definition and select **TRY IT**.
|
||||
|
||||
## Redoc vs. Reference vs. Portals
|
||||
## Redoc features
|
||||
|
||||
Redoc is Redocly's community-edition product. Looking for something more?
|
||||
Checkout the following feature comparison of Redocly's premium products versus Redoc:
|
||||
|
||||
| Features | Redoc | Reference | Portals |
|
||||
|------------------------------|:---------:|:---------:|:-----------:|
|
||||
| **Specs** | | | |
|
||||
| Swagger 2.0 | √ | √ | √ |
|
||||
| OpenAPI 3.0 | √ | √ | √ |
|
||||
| OpenAPI 3.1 | √ (basic) | √ | √ |
|
||||
| | | | |
|
||||
| **Theming** | | | |
|
||||
| Fonts/colors | √ | √ | √ |
|
||||
| Extra theme options | | √ | √ |
|
||||
| | | | |
|
||||
| **Performance** | | | |
|
||||
| Pagination | | √ | √ |
|
||||
| Search (enhanced) | | √ | √ |
|
||||
| Search (server-side) | | | √ |
|
||||
| | | | |
|
||||
| **Multiple APIs** | | | |
|
||||
| Multiple versions | | √ | √ |
|
||||
| Multiple APIs | | | √ |
|
||||
| API catalog | | | √ |
|
||||
| | | | |
|
||||
| **Additional features** | | | |
|
||||
| Try-it console | | √ | √ |
|
||||
| Automated code samples | | √ | √ |
|
||||
| Deep links | | √ | √ |
|
||||
| More SEO control | | | √ |
|
||||
| Contextual docs | | | √ |
|
||||
| Landing pages | | | √ |
|
||||
| React hooks for more control | | | √ |
|
||||
| Personalization | | | √ |
|
||||
| Analytics integrations | | | √ |
|
||||
| Feedback | | | Coming Soon |
|
||||
|
||||
Refer to the Redocly's documentation for more information on these products:
|
||||
|
||||
- [Portals](https://redocly.com/docs/developer-portal/introduction/)
|
||||
- [Reference](https://redocly.com/docs/api-reference-docs/getting-started/)
|
||||
- [Redoc](https://redocly.com/docs/redoc/quickstart/intro/)
|
||||
|
||||
## Features
|
||||
- Responsive three-panel design with menu/scrolling synchronization
|
||||
- [Multiple deployment options](https://redocly.com/docs/redoc/quickstart/intro/)
|
||||
- [Server-side rendering (SSR) ready](https://redocly.com/docs/redoc/quickstart/cli/#redoc-cli-commands)
|
||||
- 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/)
|
||||
|
||||
[Example repo](https://github.com/APIs-guru/create-react-app-redoc)
|
||||
- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redocly.com/docs/cli/commands/build-docs/)
|
||||
- Neat **interactive** documentation for nested objects <br>
|
||||
|
||||
|
||||
## Customization options
|
||||
[<img alt="Customization services" src="http://i.imgur.com/c4sUF7M.png" height="60px">](https://redocly.com/#services)
|
||||
- High-level grouping in side-menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension
|
||||
- Branding/customizations using the [`theme` option](https://redocly.com/docs/api-reference-docs/configuration/theming/)
|
||||
|
||||
## Support
|
||||
- OpenAPI v3.0 support
|
||||
- Basic OpenAPI v3.1 support
|
||||
- Broad OpenAPI v2.0 feature support (yes, it supports even `discriminator`) <br>
|
||||
|
||||
- Code samples support (via vendor extension) <br>
|
||||
- Code samples support (with vendor extension) <br>
|
||||
|
||||
|
||||
## Releases
|
||||
**Important:** all the 2.x releases are deployed to npm and can be used with Redocly-cdn:
|
||||
- particular release, for example, `v2.0.0`: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js
|
||||
- `latest` release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js
|
||||
## Usage
|
||||
|
||||
Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**:
|
||||
- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js
|
||||
- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js
|
||||
- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.
|
||||
Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.
|
||||
|
||||
## Version Guidance
|
||||
| Redoc Release | OpenAPI Specification |
|
||||
|:--------------|:----------------------|
|
||||
| 2.0.0-alpha.54| 3.1, 3.0.x, 2.0 |
|
||||
| 2.0.0-alpha.x | 3.0, 2.0 |
|
||||
| 1.19.x | 2.0 |
|
||||
| 1.18.x | 2.0 |
|
||||
| 1.17.x | 2.0 |
|
||||
### Generate documentation from the CLI
|
||||
|
||||
If you have Node installed, quickly generate documentation using `npx`:
|
||||
|
||||
```
|
||||
npx @redocly/cli build-docs openapi.yaml
|
||||
```
|
||||
|
||||
The tool outputs by default to a file named `redoc-static.html` that you can open in your browser.
|
||||
|
||||
> [Redocly CLI](https://github.com/Redocly/redocly-cli/) does more than docs; check it out and add linting, bundling, and more to your API workflow.
|
||||
|
||||
### Add an HTML element to the page
|
||||
|
||||
Create an HTML page, or edit an existing one, and add the following within the body tags:
|
||||
|
||||
```html
|
||||
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
Open the HTML file in your browser, and your API documentation is shown on the page.
|
||||
|
||||
Add your own `spec-url` to the `<redoc>` tag; this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details.
|
||||
|
||||
### More usage options
|
||||
|
||||
Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each.
|
||||
|
||||
## Redoc vs. 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/)
|
||||
with additional features including:
|
||||
|
||||
* Try-it console
|
||||
* Automated code samples
|
||||
* Pagination
|
||||
* Extra theme options
|
||||
|
||||
### Documentation and resources
|
||||
|
||||
- [Reference docs](https://redocly.com/docs/api-reference-docs/getting-started/) - we take care of the hosting
|
||||
- [Redoc](https://redocly.com/docs/redoc/) - detailed documentation for this open source project (also in the `docs/` folder)
|
||||
- [Command-line interface to bundle your docs into a web-ready HTML file](https://redocly.com/docs/cli/commands/build-docs/)
|
||||
- API linting, bundling, and much more with open source [Redocly CLI](https://redocly.com/docs/cli)
|
||||
|
||||
## Showcase
|
||||
|
||||
A sample of the organizations using Redocly tools in the wild:
|
||||
|
||||
- [Rebilly](https://api-reference.rebilly.com/)
|
||||
- [Docker Engine](https://docs.docker.com/engine/api/v1.25/)
|
||||
- [Zuora](https://www.zuora.com/developer/api-reference/)
|
||||
|
|
@ -129,64 +105,17 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d
|
|||
- [APIs.guru](https://apis.guru/api-doc/)
|
||||
- [BoxKnight](https://www.docs.boxknight.com/)
|
||||
|
||||
## Lint OpenAPI definitions
|
||||
|
||||
Redocly CLI is an [open source command-line tool](https://github.com/Redocly/redocly-cli) that you can use to lint
|
||||
your OpenAPI definition. Linting helps you to catch errors and inconsistencies in your
|
||||
OpenAPI definition before publishing.
|
||||
|
||||
Learn more about [API standards and linting](https://redocly.com/docs/cli/api-standards/) in the main Redocly documentation.
|
||||
|
||||
## Deployment
|
||||
|
||||
### TL;DR final code example
|
||||
|
||||
To render your OpenAPI definition using Redoc, use the following HTML code sample and
|
||||
replace the `spec-url` attribute with the url or local file address to your definition.
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Redoc</title>
|
||||
<!-- needed for adaptive design -->
|
||||
<meta charset="utf-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
|
||||
|
||||
<!--
|
||||
Redoc doesn't change outer page styles
|
||||
-->
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
For step-by-step instructions for how to get started using Redoc
|
||||
to render your OpenAPI definition, refer to the
|
||||
[**Redoc quickstart guide**](https://redocly.com/docs/redoc/quickstart/) and [**How to use the HTML element**](https://redocly.com/docs/redoc/deployment/html/).
|
||||
|
||||
_Pull requests to add your own API page to the list are welcome_
|
||||
|
||||
## Configuration
|
||||
|
||||
### Security Definition location
|
||||
You can inject the Security Definitions widget into any place in your definition `description`.
|
||||
For more information, refer to [Security definitions injection](docs/security-definitions-injection.md).
|
||||
Redoc is highly configurable, see the [configuration documentation](docs/config.md) for details.
|
||||
|
||||
### OpenAPI specification extensions
|
||||
Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/):
|
||||
|
||||
* [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo
|
||||
* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc
|
||||
* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etc
|
||||
* [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples
|
||||
* [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests
|
||||
* [`x-nullable`](docs/redoc-vendor-extensions.md#x-nullable) - mark schema param as a nullable
|
||||
|
|
@ -195,130 +124,23 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api
|
|||
* [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
|
||||
* [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore
|
||||
* [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys
|
||||
* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button
|
||||
* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator
|
||||
* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
|
||||
* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - for Response object, use as the response button text, with description rendered under the button
|
||||
* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - in Schemas, uses this to solve name-clash issues with the standard discriminator
|
||||
* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
|
||||
|
||||
### `<redoc>` options object
|
||||
You can use all of the following options with the standalone version of the <redoc> tag by kebab-casing them. For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`.
|
||||
## Releases
|
||||
|
||||
* `disableSearch` - disable search indexing and search box.
|
||||
* `minCharacterLengthToInitSearch` - set minimal characters length to init search, default `3`, minimal `1`.
|
||||
* `expandDefaultServerVariables` - enable expanding default server variables, default `false`.
|
||||
* `expandResponses` - specify which responses to expand by default by response codes. Values should be passed as comma-separated list without spaces e.g. `expandResponses="200,201"`. Special value `"all"` expands all responses by default. Be careful: this option can slow-down documentation rendering time.
|
||||
* `generatedPayloadSamplesMaxDepth` - set the maximum render depth for JSON payload samples (responses and request body). The default value is `10`.
|
||||
* `maxDisplayedEnumValues` - display only specified number of enum values. hide rest values under spoiler.
|
||||
* `hideDownloadButton` - do not show "Download" spec button. **THIS DOESN'T MAKE YOUR SPEC PRIVATE**, it just hides the button.
|
||||
* `downloadFileName` - set a custom file name for the downloaded API definition file.
|
||||
* `downloadDefinitionUrl` - If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here opens when that button is selected. Provide it as an absolute URL with the full URI scheme.
|
||||
* `hideHostname` - if set, the protocol and hostname is not shown in the operation definition.
|
||||
* `hideLoading` - do not show loading animation. Useful for small docs.
|
||||
* `hideFab` - do not show FAB in mobile view. Useful for implementing a custom floating action button.
|
||||
* `hideSchemaPattern` - if set, the pattern is not shown in the schema.
|
||||
* `hideSingleRequestSampleTab` - do not show the request sample tab for requests with only one sample.
|
||||
* `showObjectSchemaExamples` - show object schema example in the properties, default `false`.
|
||||
* `expandSingleSchemaField` - automatically expand single field in a schema
|
||||
* `schemaExpansionLevel` - specifies whether to automatically expand schemas. Special value `"all"` expands all levels. The default value is `0`.
|
||||
* `jsonSampleExpandLevel` - set the default expand level for JSON payload samples (responses and request body). Special value `"all"` expands all levels. The default value is `2`.
|
||||
* `hideSchemaTitles` - do not display schema `title` next to to the type
|
||||
* `simpleOneOfTypeLabel` - show only unique oneOf types in the label without titles
|
||||
* `sortEnumValuesAlphabetically` - set to true, sorts all enum values in all schemas alphabetically
|
||||
* `sortOperationsAlphabetically` - set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically
|
||||
* `sortTagsAlphabetically` - set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically
|
||||
* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`.
|
||||
* `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
|
||||
* `onlyRequiredInSamples` - shows only required fields in request samples.
|
||||
* `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one.
|
||||
* `requiredPropsFirst` - show required properties first ordered in the same order as in `required` array.
|
||||
* `scrollYOffset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc;
|
||||
`scrollYOffset` can be specified in various ways:
|
||||
* **number**: A fixed number of pixels to be used as offset.
|
||||
* **selector**: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as offset.
|
||||
* **function**: A getter function. Must return a number representing the offset (in pixels).
|
||||
* `showExtensions` - show vendor extensions ("x-" fields). Extensions used by Redoc are ignored. Can be boolean or an array of `string` with names of extensions to display.
|
||||
* `sortPropsAlphabetically` - sort properties alphabetically.
|
||||
* `payloadSampleIdx` - if set, payload sample is inserted at this index or last. Indexes start from 0.
|
||||
* `theme` - Redoc theme. For details check [theme docs](#redoc-theme-object).
|
||||
* `untrustedSpec` - if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. **Disabled by default** for performance reasons. **Enable this option if you work with untrusted user data!**
|
||||
* `nonce` - if set, the provided value is injected in every injected HTML element in the `nonce` attribute. Useful when using CSP, see https://webpack.js.org/guides/csp/.
|
||||
* `sideNavStyle` - can be specified in various ways:
|
||||
* **summary-only**: displays a summary in the sidebar navigation item. (**default**)
|
||||
* **path-only**: displays a path in the sidebar navigation item.
|
||||
* **id-only**: displays the operation id with a fallback to the path in the sidebar navigation item.
|
||||
* `showWebhookVerb` - when set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar.
|
||||
**The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch.**
|
||||
|
||||
All the 2.x releases are deployed to npm and can be used with Redocly-cdn:
|
||||
- particular release, for example, `v2.0.0`: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js
|
||||
- `latest` release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js
|
||||
|
||||
Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**:
|
||||
- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js
|
||||
- `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js
|
||||
- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.
|
||||
|
||||
### `<redoc>` theme object
|
||||
* `spacing`
|
||||
* `unit`: 5 # main spacing unit used in autocomputed theme values later
|
||||
* `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
|
||||
* `sectionVertical`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
|
||||
* `breakpoints` # breakpoints for switching three/two and mobile view layouts
|
||||
* `small`: '50rem'
|
||||
* `medium`: '85rem'
|
||||
* `large`: '105rem'
|
||||
* `colors`
|
||||
* `tonalOffset`: 0.3 # default tonal offset used in computations
|
||||
* `typography`
|
||||
* `fontSize`: '14px'
|
||||
* `lineHeight`: '1.5em'
|
||||
* `fontWeightRegular`: '400'
|
||||
* `fontWeightBold`: '600'
|
||||
* `fontWeightLight`: '300'
|
||||
* `fontFamily`: 'Roboto, sans-serif'
|
||||
* `smoothing`: 'antialiased'
|
||||
* `optimizeSpeed`: true
|
||||
* `headings`
|
||||
* `fontFamily`: 'Montserrat, sans-serif'
|
||||
* `fontWeight`: '400'
|
||||
* `lineHeight`: '1.6em'
|
||||
* `code` # inline code styling
|
||||
* `fontSize`: '13px'
|
||||
* `fontFamily`: 'Courier, monospace'
|
||||
* `lineHeight`: # COMPUTED: typography.lineHeight
|
||||
* `fontWeight`: # COMPUTED: typography.fontWeightRegular
|
||||
* `color`: '#e53935'
|
||||
* `backgroundColor`: 'rgba(38, 50, 56, 0.05)'
|
||||
* `wrap`: false # whether to break word for inline blocks (otherwise they can overflow)
|
||||
* `links`
|
||||
* `color`: # COMPUTED: colors.primary.main
|
||||
* `visited`: # COMPUTED: typography.links.color
|
||||
* `hover`: # COMPUTED: lighten(0.2 typography.links.color)
|
||||
* `textDecoration`: 'auto'
|
||||
* `hoverTextDecoration`: 'auto'
|
||||
* `sidebar`
|
||||
* `width`: '260px'
|
||||
* `backgroundColor`: '#fafafa'
|
||||
* `textColor`: '#333333'
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main
|
||||
* `groupItems` # Group headings
|
||||
* `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor
|
||||
* `textTransform`: 'uppercase'
|
||||
* `level1Items` # Level 1 items like tags or section 1st level items
|
||||
* `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor
|
||||
* `textTransform`: 'none'
|
||||
* `arrow` # sidebar arrow
|
||||
* `size`: '1.5em'
|
||||
* `color`: # COMPUTED: theme.sidebar.textColor
|
||||
* `logo`
|
||||
* `maxHeight`: # COMPUTED: sidebar.width
|
||||
* `maxWidth`: # COMPUTED: sidebar.width
|
||||
* `gutter`: '2px' # logo image padding
|
||||
* `rightPanel`
|
||||
* `backgroundColor`: '#263238'
|
||||
* `width`: '40%'
|
||||
* `textColor`: '#ffffff'
|
||||
* `servers`
|
||||
* `overlay`
|
||||
* `backgroundColor`: '#fafafa'
|
||||
* `textColor`: '#263238'
|
||||
* `url`
|
||||
* `backgroundColor`: '#fff'
|
||||
* `fab`
|
||||
* `backgroundColor`: '#263238'
|
||||
* `color`: '#ffffff'
|
||||
|
||||
-----------
|
||||
## Development
|
||||
see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
||||
|
|
|
|||
266
docs/config.md
Normal file
266
docs/config.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
# Configure Redoc
|
||||
|
||||
Getting your documentation just right is important, and Redoc comes with many configuration options to help you succeed in that mission.
|
||||
|
||||
Each deployment type has documentation on how to configure options for that type of Redoc project. This page lists all the options you can use with Redoc.
|
||||
|
||||
**Versions: 2.x**
|
||||
|
||||
:::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).
|
||||
For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`.
|
||||
|
||||
:::
|
||||
|
||||
## Functional settings
|
||||
|
||||
|
||||
### disableSearch
|
||||
|
||||
Disables search indexing and hides the search box from the API documentation page.
|
||||
|
||||
### minCharacterLengthToInitSearch
|
||||
|
||||
Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search.
|
||||
|
||||
_Default: 3_
|
||||
|
||||
### expandDefaultServerVariables
|
||||
|
||||
Enables or disables expanding default server variables.
|
||||
|
||||
### expandResponses
|
||||
|
||||
Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.
|
||||
|
||||
### expandSingleSchemaField
|
||||
|
||||
Automatically expands the single field in a schema.
|
||||
|
||||
### hideDownloadButton
|
||||
|
||||
Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.
|
||||
|
||||
### hideHostname
|
||||
|
||||
If set to `true`, the protocol and hostname are not shown in the operation definition.
|
||||
|
||||
### hideLoading
|
||||
|
||||
Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.
|
||||
|
||||
### hideRequestPayloadSample
|
||||
|
||||
Hides request payload examples.
|
||||
|
||||
### hideOneOfDescription
|
||||
|
||||
If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema.
|
||||
|
||||
### hideSchemaPattern
|
||||
|
||||
If set to `true`, the pattern is not shown in the schema.
|
||||
|
||||
### hideSchemaTitles
|
||||
|
||||
Hides the schema title next to to the type.
|
||||
|
||||
### hideSecuritySection
|
||||
|
||||
Hides the Security panel section.
|
||||
|
||||
### hideSingleRequestSampleTab
|
||||
|
||||
Hides the request sample tab for requests with only one sample.
|
||||
|
||||
### htmlTemplate
|
||||
|
||||
Sets the path to the optional HTML file used to modify the layout of the reference docs page.
|
||||
|
||||
### jsonSampleExpandLevel
|
||||
|
||||
Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.
|
||||
|
||||
_Default: 2_
|
||||
|
||||
### maxDisplayedEnumValues
|
||||
|
||||
Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.
|
||||
|
||||
### menuToggle
|
||||
|
||||
If set to `true`, selecting an expanded item in the sidebar twice collapses it.
|
||||
|
||||
_Default: true_
|
||||
|
||||
### nativeScrollbars
|
||||
|
||||
If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.
|
||||
|
||||
### onlyRequiredInSamples
|
||||
|
||||
Shows only required fields in request samples.
|
||||
|
||||
### pathInMiddlePanel
|
||||
|
||||
Shows the path link and HTTP verb in the middle panel instead of the right panel.
|
||||
|
||||
### payloadSampleIdx
|
||||
|
||||
If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0.
|
||||
|
||||
### requiredPropsFirst
|
||||
|
||||
Shows required properties in schemas first, ordered in the same order as in the required array.
|
||||
|
||||
### schemaExpansionLevel
|
||||
|
||||
Specifies whether to automatically expand schemas in Reference docs. Set it to `all` to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, `schemaExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically.
|
||||
|
||||
### scrollYOffset
|
||||
|
||||
Specifies a vertical scroll-offset.
|
||||
This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.
|
||||
|
||||
Note that you can specify the `scrollYOffset` value in any of the following ways:
|
||||
- as a number - a fixed number of pixels to be used as the offset.
|
||||
- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset.
|
||||
- a function (advanced) - a getter function. Must return a number representing the offset (in pixels).
|
||||
|
||||
### showExtensions
|
||||
|
||||
Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to `true`, all specification extensions are shown.
|
||||
|
||||
### showObjectSchemaExamples
|
||||
|
||||
Shows object schema example in the properties; default `false`.
|
||||
|
||||
### showWebhookVerb
|
||||
|
||||
When set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar.
|
||||
|
||||
### simpleOneOfTypeLabel
|
||||
|
||||
Shows only unique `oneOf` types in the label without titles.
|
||||
|
||||
### sortEnumValuesAlphabetically
|
||||
|
||||
When set to `true`, sorts all enum values in all schemas alphabetically.
|
||||
|
||||
### sortOperationsAlphabetically
|
||||
|
||||
When set to `true`, sorts operations in the navigation sidebar and in the middle panel alphabetically.
|
||||
|
||||
### sortPropsAlphabetically
|
||||
|
||||
When set to `true`, sorts properties in all schemas alphabetically.
|
||||
|
||||
### sortTagsAlphabetically
|
||||
|
||||
When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set the `sortOperationsAlphabetically` setting to `true`.
|
||||
|
||||
_Default: false_
|
||||
|
||||
### untrustedDefinition
|
||||
|
||||
If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
|
||||
|
||||
## Theme settings
|
||||
|
||||
* `spacing`
|
||||
* `unit`: 5 # main spacing unit used in autocomputed theme values later
|
||||
* `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
|
||||
* `sectionVertical`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
|
||||
* `breakpoints` # breakpoints for switching three/two and mobile view layouts
|
||||
* `small`: '50rem'
|
||||
* `medium`: '85rem'
|
||||
* `large`: '105rem'
|
||||
* `colors`
|
||||
* `tonalOffset`: 0.3 # default tonal offset used in computations
|
||||
* `typography`
|
||||
* `fontSize`: '14px'
|
||||
* `lineHeight`: '1.5em'
|
||||
* `fontWeightRegular`: '400'
|
||||
* `fontWeightBold`: '600'
|
||||
* `fontWeightLight`: '300'
|
||||
* `fontFamily`: 'Roboto, sans-serif'
|
||||
* `smoothing`: 'antialiased'
|
||||
* `optimizeSpeed`: true
|
||||
* `headings`
|
||||
* `fontFamily`: 'Montserrat, sans-serif'
|
||||
* `fontWeight`: '400'
|
||||
* `lineHeight`: '1.6em'
|
||||
* `code` # inline code styling
|
||||
* `fontSize`: '13px'
|
||||
* `fontFamily`: 'Courier, monospace'
|
||||
* `lineHeight`: # COMPUTED: typography.lineHeight
|
||||
* `fontWeight`: # COMPUTED: typography.fontWeightRegular
|
||||
* `color`: '#e53935'
|
||||
* `backgroundColor`: 'rgba(38, 50, 56, 0.05)'
|
||||
* `wrap`: false # whether to break word for inline blocks (otherwise they can overflow)
|
||||
* `links`
|
||||
* `color`: # COMPUTED: colors.primary.main
|
||||
* `visited`: # COMPUTED: typography.links.color
|
||||
* `hover`: # COMPUTED: lighten(0.2 typography.links.color)
|
||||
* `textDecoration`: 'auto'
|
||||
* `hoverTextDecoration`: 'auto'
|
||||
* `sidebar`
|
||||
* `width`: '260px'
|
||||
* `backgroundColor`: '#fafafa'
|
||||
* `textColor`: '#333333'
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main
|
||||
* `groupItems` # Group headings
|
||||
* `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor
|
||||
* `textTransform`: 'uppercase'
|
||||
* `level1Items` # Level 1 items like tags or section 1st level items
|
||||
* `activeBackgroundColor`: # COMPUTED: theme.sidebar.backgroundColor
|
||||
* `activeTextColor`: # COMPUTED: theme.sidebar.activeTextColor
|
||||
* `textTransform`: 'none'
|
||||
* `arrow` # sidebar arrow
|
||||
* `size`: '1.5em'
|
||||
* `color`: # COMPUTED: theme.sidebar.textColor
|
||||
* `logo`
|
||||
* `maxHeight`: # COMPUTED: sidebar.width
|
||||
* `maxWidth`: # COMPUTED: sidebar.width
|
||||
* `gutter`: '2px' # logo image padding
|
||||
* `rightPanel`
|
||||
* `backgroundColor`: '#263238'
|
||||
* `width`: '40%'
|
||||
* `textColor`: '#ffffff'
|
||||
* `servers`
|
||||
* `overlay`
|
||||
* `backgroundColor`: '#fafafa'
|
||||
* `textColor`: '#263238'
|
||||
* `url`
|
||||
* `backgroundColor`: '#fff'
|
||||
* `fab`
|
||||
* `backgroundColor`: '#263238'
|
||||
* `color`: '#ffffff'
|
||||
|
||||
## Additional customization
|
||||
|
||||
### Security Definition location
|
||||
|
||||
You can inject the Security Definitions widget into any place in your definition `description`.
|
||||
For more information, refer to [Security definitions injection](./security-definitions-injection.md).
|
||||
|
||||
### OpenAPI specification extensions
|
||||
|
||||
Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/):
|
||||
* [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo
|
||||
* [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc
|
||||
* [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples
|
||||
* [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests
|
||||
* [`x-nullable`](docs/redoc-vendor-extensions.md#x-nullable) - mark schema param as a nullable
|
||||
* [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
|
||||
* [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) - group tags by categories in the side menu
|
||||
* [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
|
||||
* [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore
|
||||
* [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys
|
||||
* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button
|
||||
* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator
|
||||
* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
|
||||
|
||||
|
||||
|
|
@ -1,123 +1,144 @@
|
|||
---
|
||||
title: Use the Redoc HTML element
|
||||
title: Use Redoc in HTML
|
||||
redirectFrom:
|
||||
- /docs/redoc/quickstart/html/
|
||||
- /docs/redoc/quickstart/
|
||||
---
|
||||
|
||||
# How to use the Redoc HTML element
|
||||
# Use Redoc in HTML
|
||||
|
||||
## Step 1 - Install Redoc
|
||||
To render API documentation in an HTML page, start with the template below and
|
||||
replace the `spec-url` value with the local file path or URL of your API
|
||||
description.
|
||||
|
||||
You can install Redoc using one of the following package managers:
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Redoc</title>
|
||||
<!-- needed for adaptive design -->
|
||||
<meta charset="utf-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
|
||||
|
||||
- [npm](https://docs.npmjs.com/about-npm)
|
||||
- [yarn](https://classic.yarnpkg.com/en/docs/getting-started)
|
||||
<!--
|
||||
Redoc doesn't change outer page styles
|
||||
-->
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
:::attention Initialize your package manager
|
||||
If you do not have a `package.json` file in your project directory,
|
||||
you need to add one by initializing npm or yarn in your project. Use the command `npm init` for npm,
|
||||
or `yarn init` for yarn. These initialization commands lead you through the process
|
||||
of creating a `package.json` file in your project.
|
||||
:::Success URL or local file
|
||||
|
||||
Set `spec-url` to a relative path if the file is local, e.g. `spec-url=my-api.yaml`. Use a full URL like the example above if it's hosted elsewhere.
|
||||
|
||||
For more information, see
|
||||
[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)
|
||||
in the npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/)
|
||||
in the yarn documentation.
|
||||
:::
|
||||
|
||||
### Install Redoc with yarn
|
||||
Open the HTML file in your browser to see the HTML documentation rendering. You may want to read the next section and add some configuration to make your documentation your own.
|
||||
|
||||
After navigating to your project directory in your terminal, use the following command:
|
||||
## Configure Redoc
|
||||
|
||||
```bash
|
||||
yarn add redoc
|
||||
Redoc is highly configurable, find a [full list of configuration options](../config.md) on the dedicated page.
|
||||
|
||||
To configure Redoc in HTML, add the property names to the HTML tag. Here's an example that makes all the required properties display first in the list:
|
||||
|
||||
```html
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json' required-props-first=true></redoc>
|
||||
```
|
||||
|
||||
### Install Redoc with npm
|
||||
Any of the individual properties can be added to the tag, as many as you need to get your API docs set up as you like them.
|
||||
|
||||
After navigating to your project directory in your terminal, use the following command:
|
||||
### Theme configuration
|
||||
|
||||
```bash
|
||||
npm i redoc
|
||||
The `theme` configuration setting is more complex since it represents many nested options, you can supply these as a JSON string to the `theme` attribute. For example, to change the sidebar color you would use a tag like this:
|
||||
|
||||
```html
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'
|
||||
required-props-first=true
|
||||
theme='{
|
||||
"sidebar": {
|
||||
"backgroundColor": "lightblue"
|
||||
}
|
||||
}'
|
||||
></redoc>
|
||||
```
|
||||
|
||||
## Step 2 - Reference the Redoc script
|
||||
Check out the [list of options for theme configuration](../config.md#theme-settings) and build up the configuration that suits your API needs.
|
||||
|
||||
## Advanced options
|
||||
|
||||
### The Redoc object
|
||||
|
||||
As an alternative to the HTML tag, you can also initialise Redoc in a web page using the Redoc object and invoking it from JavaScript. This is useful for situations where you want to create dynamic content in a page, and also provides a simple way to attach the Redoc element to an existing container.
|
||||
|
||||
The Redoc object offers an `init` function:
|
||||
|
||||
```js
|
||||
Redoc.init(specOrSpecUrl, options, element, callback)
|
||||
```
|
||||
- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a file name/URL to the
|
||||
definition in JSON or YAML format.
|
||||
- `options`: See the [configuration reference](../config.md).
|
||||
- `element`: DOM element Redoc is inserted into.
|
||||
- `callback`(optional): Callback to be called after Redoc has been fully rendered.
|
||||
It is also called on errors with `error` as the first argument.
|
||||
|
||||
Call `Redoc.init()` from the JavaScript on a web page to add the element to the named container. Below is an example of an HTML page with a `<div>` tag, and the JavaScript to add the Redoc object to it.
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head />
|
||||
<body>
|
||||
<H1>Redoc in action</H1>
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
<div id="redoc-container"></div>
|
||||
|
||||
<script>
|
||||
Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
|
||||
"expandResponses": "200,400"
|
||||
}, document.getElementById('redoc-container'))
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
This example also sets the configuration for `expandResponses` so all 200 and 400 status responses are shown unfolded and with their details visible when the page loads.
|
||||
|
||||
### Self-host dependencies
|
||||
|
||||
You can reference the Redoc script using either a link to the files hosted on a CDN
|
||||
or the files located in your `node modules` folder.
|
||||
or install to your `node-modules` folder. Using the CDN is the simplest option, but
|
||||
if you need to host in a closed environment or have requirements around external
|
||||
dependencies, it may be useful to self-host.
|
||||
|
||||
### CDN link
|
||||
|
||||
To reference the Redoc script with a CDN link:
|
||||
The main example shows using the CDN:
|
||||
|
||||
```html
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
### Node modules link
|
||||
If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`:
|
||||
|
||||
To reference the Redoc script with a node modules link:
|
||||
```
|
||||
npm install redoc
|
||||
```
|
||||
|
||||
_(Yarn users can install the `redoc` package with `yarn`)_.
|
||||
|
||||
You can then reference the Redoc script with a node modules link:
|
||||
|
||||
```html
|
||||
<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
## Step 3 - Add the <redoc> element
|
||||
|
||||
You can add the <redoc> element to your HTML page and reference your OpenAPI
|
||||
definition using the `spec-url` attribute, or you can initialize Redoc using
|
||||
a globally exposed Redoc object.
|
||||
|
||||
### The `spec-url` attribute
|
||||
|
||||
To add the <redoc> element with the `spec-url` attribute:
|
||||
|
||||
```html
|
||||
<redoc spec-url="url/to/your/spec"></redoc>
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
```html
|
||||
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
|
||||
```
|
||||
|
||||
You can also use a local file (JSON or YAML) in your project, for instance:
|
||||
|
||||
```html
|
||||
<redoc spec-url="dist.json"></redoc>
|
||||
```
|
||||
|
||||
### The Redoc object
|
||||
|
||||
To add the <redoc> element with a globally exposed Redoc object:
|
||||
|
||||
```js
|
||||
Redoc.init(specOrSpecUrl, options, element, callback)
|
||||
```
|
||||
- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the
|
||||
definition in JSON or YAML format.
|
||||
- `options`: See [`theme.openapi` object](/docs/api-reference-docs/configuration/functionality.mdx) reference.
|
||||
- `element`: DOM element Redoc is inserted into.
|
||||
- `callback`(optional): Callback to be called after Redoc has been fully rendered.
|
||||
It is also called on errors with `error` as the first argument.
|
||||
|
||||
#### Examples
|
||||
|
||||
```html
|
||||
<script>
|
||||
Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
|
||||
scrollYOffset: 50
|
||||
}, document.getElementById('redoc-container'))
|
||||
</script>
|
||||
```
|
||||
|
||||
You can also use a local file (JSON or YAML) in your project, for instance:
|
||||
|
||||
```html
|
||||
<script>
|
||||
Redoc.init('dist.yaml', {
|
||||
scrollYOffset: 50
|
||||
}, document.getElementById('redoc-container'))
|
||||
</script>
|
||||
```
|
||||
|
|
|
|||
96
docs/index.md
Normal file
96
docs/index.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
title: Redoc
|
||||
---
|
||||
|
||||
# Redoc: Open source API documentation tool
|
||||
|
||||
Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description (Swagger is also still supported). With one command, create your documentation, and customize it to meet the needs of your users.
|
||||
|
||||
Redoc is based around a three panel layout, with clear sections for navigation, detailed documentation, and request/response examples.
|
||||
|
||||
## Headline features
|
||||
|
||||
* Modern layout with extensive customization options.
|
||||
* Support for OpenAPI 3.1, 3.0 and older 2.0 and Swagger formats.
|
||||
* Embed or build standalone HTML documentation.
|
||||
* CLI tool for easy automation and local development.
|
||||
|
||||
## Demo
|
||||
|
||||
[Try the live demo](https://redocly.github.io/redoc/) and upload your own API specification there to try.
|
||||
|
||||
## Usage
|
||||
|
||||
Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.
|
||||
|
||||
### Generate documentation from the CLI
|
||||
|
||||
If you have Node installed, quickly generate documentation using `npx`:
|
||||
|
||||
```
|
||||
npx @redocly/cli build-docs openapi.yaml
|
||||
```
|
||||
|
||||
The tool outputs by default to a file named `redoc-static.html` that you can open in your browser.
|
||||
|
||||
> [Redocly CLI](https://github.com/Redocly/redocly-cli/) does more than docs, check it out and add linting, bundling and more to your API workflow.
|
||||
|
||||
### Add an HTML element to the page
|
||||
|
||||
Create an HTML page, or edit an existing one, and add the following:
|
||||
|
||||
```html
|
||||
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
Open the HTML file in your browser, and your API documentation is shown on the page.
|
||||
|
||||
Add your own `spec-url` to the `<redoc>` tag; this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details.
|
||||
|
||||
### More usage options
|
||||
|
||||
Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each.
|
||||
|
||||
## Configure Redoc
|
||||
|
||||
Redoc is highly configurable. Each deployment option accepts configuration in a way that's appropriate to that platform, but the options are the same for each. For example:
|
||||
|
||||
* Using [Redocly CLI](../cli/index.md), configuration goes in the `redocly.yaml` file, or can be supplied as command line parameters, such as `--theme.openapi.disableSearch`.
|
||||
* Using HTML or React, configure by setting `option` in the tag.
|
||||
|
||||
Here's a sample `redocly.yaml` configuration file, showing a few common settings and tweaking some of the visual theme settings:
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
openapi:
|
||||
disableSearch: true
|
||||
expandResponses: 200,202
|
||||
jsonSampleExpandLevel: 1
|
||||
|
||||
theme:
|
||||
sidebar:
|
||||
backgroundColor: '#eae0cc'
|
||||
textColor: '#3d005b'
|
||||
colors:
|
||||
primary:
|
||||
main: '#660099'
|
||||
typography:
|
||||
fontSize: 14pt
|
||||
headings:
|
||||
fontWeight: bold
|
||||
```
|
||||
|
||||
Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this:
|
||||
|
||||
```
|
||||
redocly preview-docs openapi.yaml
|
||||
```
|
||||
|
||||
There are many, many more options available. Visit the [configuration reference](./config.md) for a complete list.
|
||||
|
||||
## Next steps
|
||||
|
||||
* If you are new to OpenAPI, try the [OpenAPI starter project](../../cli/openapi-starter/) for a great introduction.
|
||||
* Ready to build documentation from an existing OpenAPI file? Go to the [Redoc quickstart](./quickstart.md) and get started.
|
||||
* Learn more about the project by visiting [Redoc on GitHub](https://github.com/Redocly/redoc).
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
---
|
||||
title: Redoc quickstart guide
|
||||
---
|
||||
|
||||
# Redoc quickstart guide
|
||||
|
||||
To render your OpenAPI definition using Redoc, use the following HTML code sample and
|
||||
replace the `spec-url` attribute with the URL or local file address to your definition.
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Redoc</title>
|
||||
<!-- needed for adaptive design -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
|
||||
rel="stylesheet"
|
||||
/>
|
||||
|
||||
<!--
|
||||
Redoc doesn't change outer page styles
|
||||
-->
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<!--
|
||||
Redoc element with link to your OpenAPI definition
|
||||
-->
|
||||
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
|
||||
<!--
|
||||
Link to Redoc JavaScript on CDN for rendering standalone element
|
||||
-->
|
||||
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
:::attention Redoc requires an HTTP server to run locally
|
||||
|
||||
Loading local OpenAPI definitions is impossible without running a web server because of issues with
|
||||
[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and
|
||||
other security reasons. Refer to [Running Redoc locally](./deployment/intro.md#how-to-run-redoc-locally) for more information.
|
||||
|
||||
:::
|
||||
|
||||
For a more detailed explanation with step-by-step instructions and additional options for using Redoc, refer to the [Redoc deployment guide](./deployment/intro.md).
|
||||
Loading…
Reference in New Issue
Block a user