Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add optional markdownGenerators config option #567

Merged
merged 2 commits into from
May 5, 2023
Merged

Add optional markdownGenerators config option #567

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a0c3287
Add optional markdownGenerators config option to allow high level of …
jgarrow May 4, 2023
6145daf
Update docs to add markdownGenerators config option
jgarrow May 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions demo/docs/intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,20 +297,21 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following

`config` can be configured with the following options:

| Name | Type | Default | Description |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. |
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. |
| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. |
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
| `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
| Name | Type | Default | Description |
| -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. |
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. |
| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. |
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
| `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for markdown generator configuration. See below for a list of supported options. |

### sidebarOptions

Expand Down Expand Up @@ -344,6 +345,22 @@ You may optionally configure a `sidebarOptions`. In doing so, an individual `sid
All versions will automatically inherit `sidebarOptions` from the parent/base config.
:::

### markdownGenerators

`markdownGenerators` can be configured with the following options:

| Name | Type | Default | Description |
| ------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------|
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |

:::info NOTE
If a config option is not provided, its default markdown generator will be used.

This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages.
:::

## Installing from Template

Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
Expand Down Expand Up @@ -397,4 +414,4 @@ For more insight into why we decided to completely fork see [#47](https://github

See [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for our support agreement and guidelines.

If you believe you found a bug or have an idea you'd like to suggest you may [report an issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/new/choose) or [start a discussion](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/discussions/new/choose).
If you believe you found a bug or have an idea you'd like to suggest you may [report an issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/new/choose) or [start a discussion](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/discussions/new/choose).
23 changes: 18 additions & 5 deletions packages/docusaurus-plugin-openapi-docs/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,14 @@ export default function pluginOpenAPIDocs(
let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;

async function generateApiDocs(options: APIOptions, pluginId: any) {
let { specPath, outputDir, template, downloadUrl, sidebarOptions } =
options;
let {
specPath,
outputDir,
template,
markdownGenerators,
downloadUrl,
sidebarOptions,
} = options;

// Remove trailing slash before proceeding
outputDir = outputDir.replace(/\/$/, "");
Expand Down Expand Up @@ -237,6 +243,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
\`\`\`
`;

const apiPageGenerator =
markdownGenerators?.createApiPageMD ?? createApiPageMD;
const infoPageGenerator =
markdownGenerators?.createInfoPageMD ?? createInfoPageMD;
const tagPageGenerator =
markdownGenerators?.createTagPageMD ?? createTagPageMD;

loadedApi.map(async (item) => {
if (item.type === "info") {
if (downloadUrl && isURL(downloadUrl)) {
Expand All @@ -245,10 +258,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
}
const markdown =
item.type === "api"
? createApiPageMD(item)
? apiPageGenerator(item)
: item.type === "info"
? createInfoPageMD(item)
: createTagPageMD(item);
? infoPageGenerator(item)
: tagPageGenerator(item);
item.markdown = markdown;
if (item.type === "api") {
item.json = JSON.stringify(item.api);
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-plugin-openapi-docs/src/options.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ const sidebarOptions = Joi.object({
sidebarCollapsed: Joi.boolean(),
});

const markdownGenerators = Joi.object({
createApiPageMD: Joi.function(),
createInfoPageMD: Joi.function(),
createTagPageMD: Joi.function(),
});

export const OptionsSchema = Joi.object({
id: Joi.string().required(),
docsPluginId: Joi.string().required(),
Expand All @@ -31,6 +37,7 @@ export const OptionsSchema = Joi.object({
hideSendButton: Joi.boolean(),
showExtensions: Joi.boolean(),
sidebarOptions: sidebarOptions,
markdownGenerators: markdownGenerators,
version: Joi.string().when("versions", {
is: Joi.exist(),
then: Joi.required(),
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-plugin-openapi-docs/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,13 @@ export interface APIOptions {
[key: string]: APIVersionOptions;
};
proxy?: string;
markdownGenerators?: MarkdownGenerator;
}

export interface MarkdownGenerator {
createApiPageMD?: (pageData: ApiPageMetadata) => string;
createInfoPageMD?: (pageData: InfoPageMetadata) => string;
createTagPageMD?: (pageData: TagPageMetadata) => string;
}

export interface SidebarOptions {
Expand Down