diff --git a/website/docs/guides/migrating-to-v1.md b/website/docs/guides/migrating-to-v1.md index d3380fc5..70936de8 100644 --- a/website/docs/guides/migrating-to-v1.md +++ b/website/docs/guides/migrating-to-v1.md @@ -1,5 +1,5 @@ --- -title: Migrating to V1 +title: Migrating from v0 sidebar_position: 4 --- diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index fb337909..99804da1 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -27,6 +27,13 @@ const config: Config = { debug: Boolean(process.env.DEBUG || process.env.CI), theme: { customCss: [require.resolve('./src/custom.css')] }, docs: { + lastVersion: 'current', + versions: { + current: { + label: packageJson.version, + path: '', + }, + }, routeBasePath: '/docs', editUrl: 'https://github.com/rohit-gohri/redocusaurus/edit/main/website/', @@ -137,18 +144,10 @@ const config: Config = { ], }, { - label: `v${packageJson.version}`, + type: 'docsVersionDropdown', position: 'right', - items: [ - { - label: 'v0', - href: 'https://redocusaurus-v0.vercel.app/', - }, - { - label: 'v1 | v2', - to: '/', - }, - ], + dropdownActiveClassDisabled: true, + // 'https://redocusaurus-v0.vercel.app/', }, { type: 'localeDropdown', diff --git a/website/versioned_docs/version-0.x/Introduction.md b/website/versioned_docs/version-0.x/Introduction.md new file mode 100644 index 00000000..858dd224 --- /dev/null +++ b/website/versioned_docs/version-0.x/Introduction.md @@ -0,0 +1,20 @@ +--- +slug: / +title: Introduction +sidebar_position: 0 +author: Rohit Gohri +author_url: https://rohit.page +--- + +Redocusaurus is a preset for Docusaurus to help you integrate OpenAPI documentation via [Redoc](https://github.com/redocly/redoc/). It was created to make it easy to have API docs that live with your other documentation and look and feel like a part of it. + +## Features + +- Built with 💚 and Typescript + - In built types +- Easy to setup and already themed + - Just add the preset and pass it your YAML + - Dark Mode support +- Customizable + - Change Redoc Options + - [Swizzle](https://docusaurus.io/docs/using-themes#swizzling-theme-components) components to your needs diff --git a/website/versioned_docs/version-0.x/getting-started/Installation.md b/website/versioned_docs/version-0.x/getting-started/Installation.md new file mode 100644 index 00000000..8f82c79a --- /dev/null +++ b/website/versioned_docs/version-0.x/getting-started/Installation.md @@ -0,0 +1,101 @@ +--- +title: Installation +sidebar_position: 0 +author: Rohit Gohri +author_url: https://rohit.page +--- + +1. Install redocusaurus: + +![npm](https://img.shields.io/npm/v/redocusaurus?style=flat-square) + +```sh +npm i --save redocusaurus +``` + +1. Add it as a preset to your docusaurus config and pass options: + + - Pass it a OpenAPI spec URL + + ```js + // docusaurus.config.js + + module.exports = { + // ... + presets: [ + [ + 'redocusaurus', + { + specs: [ + { + specUrl: 'https://redocly.github.io/redoc/openapi.yaml', + }, + ], + }, + ], + ], + // ... + }; + ``` + + - Pass it a OpenAPI spec local path + + ```js + // docusaurus.config.js + + module.exports = { + // ... + presets: [ + [ + 'redocusaurus', + { + specs: [ + { + spec: 'openapi.yaml', + }, + ], + }, + ], + ], + // ... + }; + ``` + +The API Doc will be available by default at `/api/` path. If you wish to +override this path, you may set the `routePath` option. To skip adding a +route altogether, set the `addRoute` option to false. You will still be +able to reference schema elements manually using [Schema Imports](/docs/guides/schema-imports). + +```js +// docusaurus.config.js + +module.exports = { + // ... + presets: [ + [ + 'redocusaurus', + { + specs: [ + { + id: 'default-route', + // routePath: '/api/', + // addRoute: true, + }, + { + id: 'route-overridden', + routePath: '/different-path/', + // addRoute: true, + }, + { + id: 'no-route', + addRoute: false, + }, + ], + }, + ], + ], + // ... +}; +``` + +To customize it see [full plugin options](#options). diff --git a/website/versioned_docs/version-0.x/getting-started/_category_.yaml b/website/versioned_docs/version-0.x/getting-started/_category_.yaml new file mode 100644 index 00000000..73584564 --- /dev/null +++ b/website/versioned_docs/version-0.x/getting-started/_category_.yaml @@ -0,0 +1,2 @@ +label: 'Getting Started' +position: 1 diff --git a/website/versioned_docs/version-0.x/guides/_category_.yaml b/website/versioned_docs/version-0.x/guides/_category_.yaml new file mode 100644 index 00000000..b8e18877 --- /dev/null +++ b/website/versioned_docs/version-0.x/guides/_category_.yaml @@ -0,0 +1,2 @@ +label: 'Guides' +position: 2 diff --git a/website/versioned_docs/version-0.x/guides/schema-imports.mdx b/website/versioned_docs/version-0.x/guides/schema-imports.mdx new file mode 100644 index 00000000..ba885f24 --- /dev/null +++ b/website/versioned_docs/version-0.x/guides/schema-imports.mdx @@ -0,0 +1,91 @@ +--- +title: Schema Imports +--- + +import ApiSchema from '@theme/ApiSchema'; + +You can import model definitions from your API schema and render them in your Docusaurus Docs. You'll need to create an `.mdx` file and import the React Component. Read more [here about MDX in Docusaurus](https://docusaurus.io/docs/markdown-features/react). + +# Import Schema Model in Docs + +The `pointer` prop is passed on to [Redoc](https://redoc.ly/docs/resources/ref-guide/#pointer). + +```tsx +import ApiSchema from '@theme/ApiSchema'; + +; +``` + +### Results + + + +## Import Schema Model (with example) in Docs + +```tsx +import ApiSchema from '@theme/ApiSchema'; + +; +``` + +### Results + + + +## Importing Schema Model with multiple OpenAPI schemas + +If you have multiple APIs loaded with redocusaurus, then it is recommended to add `id`s to the config so that you can refer them when loading schema models. + +```js title="docusaurus.config.js" +const config = { + presets: [ + [ + 'redocusaurus', + { + specs: [ + { + id: 'using-spec-url', + specUrl: 'https://redocly.github.io/redoc/openapi.yaml', + routePath: '/examples/using-spec-url/', + }, + { + id: 'using-relative-url', + specUrl: `${process.env.DEPLOY_BASE_URL || '/'}openapi-page.yaml`, + routePath: '/examples/using-relative-url/', + }, + ], + theme: { + /** + * Highlight color for docs + */ + primaryColor: '#1890ff', + /** + * Options to pass to redoc + * @see https://github.com/redocly/redoc#redoc-options-object + */ + redocOptions: { hideDownloadButton: false, disableSearch: true }, + }, + }, + ], + '@docusaurus/preset-classic', + ], + title: 'Redocusaurus', +}; +``` + +```tsx +import ApiSchema from '@theme/ApiSchema'; + +; +; +``` + +### Results + +#### For ID `id="using-single-yaml"` + + + +#### For ID `id="using-remote-url"` + + diff --git a/website/versioned_docs/version-0.x/guides/server-side-rendering.md b/website/versioned_docs/version-0.x/guides/server-side-rendering.md new file mode 100644 index 00000000..2f6c1540 --- /dev/null +++ b/website/versioned_docs/version-0.x/guides/server-side-rendering.md @@ -0,0 +1,72 @@ +--- +title: Server Side Rendering +--- + +:::caution +**NOTE:** This is in Beta. Please [add your feedback here](https://github.com/rohit-gohri/redocusaurus/discussions/88) +::: + +## Prerequisites + +To enable SSR you have to do 2 things: + +### Updating your Root theme component + +Use the custom ServerStyle component in your [Theme Root](https://docusaurus.io/docs/using-themes#wrapper-your-site-with-root) (as mentioned [here](https://github.com/facebook/docusaurus/issues/3236#issuecomment-788953743)) for SSR like below: + +```tsx title="src/theme/Root/index.tsx" +import React from 'react'; + +import ServerStyle from '@theme/ServerStyle'; + +function Root({ children }: { children: React.Component }): JSX.Element { + return ( + <> + // TODO: Remove when docusaurus adds proper css-in-js support + + {children} + + ); +} + +export default Root; +``` + +### Use yaml files rather than urls to load OpenAPI files + +To enable SSR we need to parse the schema at build time so it needs to passed on as a yaml and it will be processed to JSON. This has a side-effect of the download button pointing to the JSON, to fix this you can also provide a `specUrl` to the original url that will be used as the download link. + +```js title="docusaurs.config.js" +const config = { + presets: [ + [ + 'redocusaurus', + { + specs: [ + { + spec: 'openapi.yaml', + /** + * This becomes the Download URL in this case, while docs are generated from `spec` + */ + specUrl: `${process.env.DEPLOY_BASE_URL || '/'}openapi-page.yaml`, + routePath: '/examples/using-spec-yaml/', + }, + ], + theme: { + /** + * Highlight color for docs + */ + primaryColor: '#1890ff', + /** + * Options to pass to redoc + * @see https://github.com/redocly/redoc#redoc-options-object + */ + redocOptions: { hideDownloadButton: false, disableSearch: true }, + }, + }, + ], + '@docusaurus/preset-classic', + ], + title: 'Redocusaurus', +}; +``` diff --git a/website/versioned_sidebars/version-0.x-sidebars.json b/website/versioned_sidebars/version-0.x-sidebars.json new file mode 100644 index 00000000..cff0c94e --- /dev/null +++ b/website/versioned_sidebars/version-0.x-sidebars.json @@ -0,0 +1,8 @@ +{ + "defaultSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/website/versions.json b/website/versions.json new file mode 100644 index 00000000..772d0506 --- /dev/null +++ b/website/versions.json @@ -0,0 +1,3 @@ +[ + "0.x" +]