Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@rohit-gohri
rohit-gohri committed Mar 7, 2024
1 parent 0f10b66 commit 8341805
Show file tree
Hide file tree
Showing 3 changed files with 110 additions and 132 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
![GitHub branch checks state](https://img.shields.io/github/checks-status/rohit-gohri/redocusaurus/main?logo=github)
[![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/fef74697/redocusaurus)

[Redoc](https://github.com/redocly/redoc) for [Docusaurus v2](https://v2.docusaurus.io/).
[Redoc](https://github.com/redocly/redoc) for [Docusaurus](https://docusaurus.io/).

## Usage

Expand Down
130 changes: 59 additions & 71 deletions packages/redocusaurus/Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,85 +2,73 @@

![npm](https://img.shields.io/npm/v/redocusaurus?style=flat-square)

[Redoc](https://github.com/redocly/redoc) for [Docusaurus v2](https://v2.docusaurus.io/).
[Redoc](https://github.com/redocly/redoc) for [Docusaurus](https://docusaurus.io/).

## Usage

1. Setup [docusaurus project](https://docusaurus.io/docs/installation)

1. Install redocusaurus:

```sh
npm i --save redocusaurus
# OR
yarn add redocusaurus
```
```sh
yarn add redocusaurus
# OR
pnpm add redocusaurus
# OR
npm i --save redocusaurus
```

1. Add it as a preset to your docusaurus config along with [@docusaurus/preset-classic](https://docusaurus.io/docs/using-plugins#docusauruspreset-classic) and pass options:

- Pass it a path to a local OpenAPI YAML file

```js
// docusaurus.config.js

module.exports = {
// ...
presets: [
// .. Your other presets' config
'@docusaurus/preset-classic',
// Redocusaurus config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
{
spec: 'openapi/openapi.yaml',
route: '/api/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
},
},
],
],
// ...
};
```

- OR Pass it a OpenAPI spec URL

```js
// docusaurus.config.js
module.exports = {
// ...
presets: [
// .. Your other presets' config
'@docusaurus/preset-classic',
// Redocusaurus config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
{
spec: 'https://redocly.github.io/redoc/openapi.yaml',
route: '/api/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
},
},
],
],
// ...
};
```
```js
// docusaurus.config.ts
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import type * as Redocusaurus from 'redocusaurus';

const config: Config = {
// ...
presets: [
// .. Your other presets' config
[
'@docusaurus/preset-classic',
{
googleAnalytics: {
trackingID: 'XXXXXX',
},
} satisfies Preset.Options,
]
// Redocusaurus config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
// Pass it a path to a local OpenAPI YAML file
{
// Redocusaurus will automatically bundle your spec into a single file during the build
spec: 'openapi/index.yaml',
route: '/api/',
},
// You can also pass it a OpenAPI spec URL
{
spec: 'https://redocly.github.io/redoc/openapi.yaml',
route: '/openapi/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
},
},
] satisfies Redocusaurus.PresetEntry,
],
// ... Rest of your config
};

export default config;
```

The API Doc will be available at the route specified (`/api/` in the example above). To customize it see [full plugin options](https://redocusaurus.vercel.app/docs/getting-started/plugin-options).

Expand Down
110 changes: 50 additions & 60 deletions website/docs/getting-started/Installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ author: Rohit Gohri
author_url: https://rohit.page
---

1. Setup [docusaurus project](https://docusaurus.io/docs/installation)

1. Install redocusaurus:

![npm](https://img.shields.io/npm/v/redocusaurus?style=flat-square)
Expand All @@ -15,69 +17,57 @@ author_url: https://rohit.page
yarn add redocusaurus
```

1. Add it as a preset to your docusaurus config along with [@docusaurus/preset-classic](https://docusaurus.io/docs/using-plugins#docusauruspreset-classic) and pass the following options:

- Pass the path to the local OpenAPI YAML file.

```js
// docusaurus.config.js

module.exports = {
// ...
presets: [
// .. Your other presets' config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
{
spec: 'openapi/openapi.yaml',
route: '/api/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
},
1. Add it as a preset to your docusaurus config along with [@docusaurus/preset-classic](https://docusaurus.io/docs/using-plugins#docusauruspreset-classic) and pass options:

```js
// docusaurus.config.ts
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import type * as Redocusaurus from 'redocusaurus';

const config: Config = {
// ...
presets: [
// .. Your other presets' config
[
'@docusaurus/preset-classic',
{
googleAnalytics: {
trackingID: 'XXXXXX',
},
],
],
// ...
};
```

- Pass the URL for the OpenAPI spec.

```js
// docusaurus.config.js
module.exports = {
// ...
presets: [
// .. Your other presets' config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
{
spec: 'https://redocly.github.io/redoc/openapi.yaml',
route: '/api/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
} satisfies Preset.Options,
]
// Redocusaurus config
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
// Pass it a path to a local OpenAPI YAML file
{
// Redocusaurus will automatically bundle your spec into a single file during the build
spec: 'openapi/index.yaml',
route: '/api/',
},
// You can also pass it a OpenAPI spec URL
{
spec: 'https://redocly.github.io/redoc/openapi.yaml',
route: '/openapi/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
},
],
],
// ...
};
```
},
] satisfies Redocusaurus.PresetEntry,
],
// ... Rest of your config
};

export default config;
```

The API Doc will be available at the path specific by `route`. To skip adding a route altogether just don't set the `route` property.
You will still be able to reference schema elements manually using [Schema Imports](/docs/guides/schema-imports) or create Custom React Pages using the data and theme components.
Expand Down

0 comments on commit 8341805

Please sign in to comment.