paloaltonetworks / docusaurus-openapi-docs Goto Github PK
View Code? Open in Web Editor NEW๐ฆ OpenAPI plugin for generating API reference docs in Docusaurus v3.
Home Page: https://docusaurus-openapi.tryingpan.dev
License: MIT License
๐ฆ OpenAPI plugin for generating API reference docs in Docusaurus v3.
Home Page: https://docusaurus-openapi.tryingpan.dev
License: MIT License
While creating schema details, sometimes the evaluated schemaName
did not match against the following conditions: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchemaDetails.ts#L55
I believe this occurs because the conditions only check for the string eval of each schema key and not the typeof
the schema itself.
All schemas should be evaluated, regardless of what the schemaName
is.
Only schemaNames with "object" or "object[]" string values are evaluated.
if (
schemaName &&
(typeof schema === "object" ||
((typeof schema as any) === "array" && typeof schema[0] === "object"))
)
Currently, circular $ref
pointers are not fully resolved. The are explicitly "ignored" by the JSON schema dereference
utility.
Ideally, circular $ref
pointers should be fully resolved, so long as serialization is not required or broken.
Some dependencies, like openapi-to-postman
, are attempting to serialize the OpenAPI object
which throws an error.
https://github.com/PaloAltoNetworks/openapi-to-postman/blob/develop/lib/common/versionUtils.js#L93
https://github.com/PaloAltoNetworks/openapi-to-postman
Refactor openapi-to-postman
to no longer require serializing the OpenAPI object
prior to converting into a postman collection. Additionally, locate and refactor any other such instances.
Ultimately, the goal would be to fully dereference and preserve circular $ref
pointers as an object
.
Currently, descriptions sourced from a URL $ref
are not rendered properly.
The idea would be to support resolving URL refs such that items like descriptions, summary, etc., can be sourced by URL, e.g. from GitHub (raw).
Dereferencing the git/URL-sourced content prior to attempting to generate API docs.
Today, if you run the plugin against a spec with URL refs (descriptions) you end up with [object Object]
:
With the new resolver/serializer, circular schema references should be replaced with a "circular" label. There are cases where this label is not properly applied (see below):
Circular label should appear next to the property with the circular reference:
createSchemaDetails
to determine if and where the label may be getting dropped/lost.See #154 deploy preview
Currently we do nothing with response examples, which could be helpful for understanding possible responses the API could return for different status codes.
In addition to response code Schema
, we can provide the end user with the option to select and view example responses for that status code, similar to how ReDoc handles it.
ReDoc example:
Not including examples, although I think they could be helpful to users.
Each status code response will have its own set of examples. Whatever we come up with should provide the ability to select which example to display.
Docusaurus 2.0.0-beta.19
and 2.0.0-beta.20
introduced breaking changes preventing us from upgrading from 2.0.0-beta.18
. This issue will be used for both bug and progress tracking as we work through the issues.
There should be a viable upgrade path moving from 2.0.0-beta.18 to beta.19 or beta.20.
Currently, we're able to run beta.19 and beta.20 in dev server only - production builds are not possible. The errors suggest possible issue with legacy or incompatible module exports in docusaurus-theme-openapi-docs
.
@ts-ignore
throughout project #80useColorMode
hook (ensure calling component is wrapped in Layout
)This issue is for tracking progression through renaming repository and packages and updating all supporting licenses and docs, e.g. READMEs, license headers, usage, screenshots, etc.
Proposed naming:
Repository: docusaurus-openapi-docs
Plugin: docusaurus-plugin-openapi-docs
Theme: docusaurus-theme-openapi-docs
Logo: TBD
Since forking the original docusaurus-openapi we have diverged enough to warrant breaking the fork and spinning off our own project. With that said, we'd like to remain friendly to the rest of the Docusaurus community by packaging and offering our version of the plugin such that other Docusaurus users may potentially use it in their projects.
README.md
(screenshots, badges and usage) #64LICENSE
(and .eslintrc.js
rules) (adopt panw license) #64CONTRIBUTING.md
#65SUPPORT.md
(adopt panw community support) #65CODE_OF_CONDUCT.md
(adopt panw if appropriate) #65docusaurus-plugin-openapi
README.md
(screenshots and usage) #68@paloaltonetworks/
scope and rename folders and package.json
"name" #69I'm using Docusaurus 2.0.0-rc.1 and getting this error:
Module not found: Error: Can't resolve '@theme/DocItemFooter' in node_modules/docusaurus-theme-openapi-docs/lib-next/theme/ApiItem'.
My plugin section looks like this:
'@docusaurus/plugin-content-docs',
{
path: 'docs/api/petstore',
routeBasePath: '/api/petstore',
id: 'apiPetstore',
sidebarPath: require.resolve('./sidebars/petstore.js'),
sidebarCollapsible: false,
docLayoutComponent: "@theme/DocPage",
docItemComponent: "@theme/ApiItem",
},
],
Thanks!
Not really, more of an enhancement.
Might be useful to expand details components by one level for desktop view. Mobile can stay collapsed by default.
I've tried expanding the details myself but it adds at least one extra click and sometimes I'm disappointed with what I see.
This is more of a UI/UX enhancement request, so I expect there might be some discussion around whether it makes sense.
I believe Docusaurus has a useWindowSize()
hook included but I'm not sure it makes sense to use in this scenario, since it's intended for React components.
Requesting support for client credentials security scheme. Could also include support for remaining security scheme types.
A solution similar to our support for API keys and basic auth.
N/A
Since we are no longer allowing users to enter their credentials it may also be a good time to cleanup the Redux slice and Authorize
button and any other unused code.
Attempting to use the yarn docusaurus gen-api-docs all
command to generate docs. Got the base route to render, but when I click on any other route I get a "This page crashed" error with "Hook useTabGroupChoice is called outside the <TabGroupChoiceProvider>
."
My config
// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion
const lightCodeTheme = require("prism-react-renderer/themes/github");
const darkCodeTheme = require("prism-react-renderer/themes/dracula");
/** @type {import('@docusaurus/types').Config} */
const config = {
title: "HailTrace",
tagline: "Developer Documentation",
url: "https://developers.hailtrace.com",
baseUrl: "/",
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
favicon: "img/favicon.ico",
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
// organizationName: "hailtrace", // Usually your GitHub org/user name.
// projectName: "docusaurus", // Usually your repo name.
// Even if you don't use internalization, you can use this field to set useful
// metadata like html lang. For example, if your site is Chinese, you may want
// to replace "en" with "zh-Hans".
i18n: {
defaultLocale: "en",
locales: ["en"],
},
presets: [
[
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve("./sidebars.js"),
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl:
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
docLayoutComponent: "@theme/DocPage",
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi-docs
},
blog: {
showReadingTime: true,
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl:
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
}),
],
],
plugins: [
[
"docusaurus-plugin-openapi-docs",
{
id: "openapi",
config: {
api: {
// Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
specPath: "openapi/openapi.yaml", // Path to designated spec file
outputDir: "api/openapi", // Output directory for generated .mdx docs
sidebarOptions: {
groupPathsBy: "tags",
},
},
},
},
],
[
"content-docs",
{
id: "openapi",
path: "api",
breadcrumbs: true,
routeBasePath: "api",
include: ["**/*.md", "**/*.mdx"],
sidebarPath: "apiSidebars.js",
docLayoutComponent: "@theme/DocPage", // This solves the providers issue and drop the need for ApiPage component
docItemComponent: "@theme/ApiItem", // Will probably need to clean this up/refactor to get it fully updated
remarkPlugins: [],
rehypePlugins: [],
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
showLastUpdateAuthor: true, // We can now add stuff like this :)
showLastUpdateTime: true,
},
],
],
themes: ["docusaurus-theme-openapi-docs"],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
navbar: {
title: "HailTrace",
logo: {
alt: "My Site Logo",
src: "img/logo.svg",
},
items: [
{
to: "/api/openapi",
position: "left",
label: "OpenApi",
},
{ to: "/blog", label: "Blog", position: "left" },
{
href: "https://github.com/facebook/docusaurus",
label: "GitHub",
position: "right",
},
],
},
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Tutorial",
to: "/docs/intro",
},
],
},
{
title: "Community",
items: [
{
label: "Stack Overflow",
href: "https://stackoverflow.com/questions/tagged/hailtrace",
},
{
label: "Twitter",
href: "https://twitter.com/hailtrace",
},
],
},
{
title: "More",
items: [
{
label: "Blog",
to: "/blog",
},
{
label: "GitHub",
href: "https://github.com/hailtrace",
},
],
},
],
copyright: `Copyright ยฉ ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
};
module.exports = config;
No, just room for improvement.
Ability to support x-logo
vendor extension, similar to ReDoc, which could be used to specify a logo to display for the API.
n/a
Was thinking we could place it in the intro doc or perhaps even find a way to include it in all API operation doc pages.
https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml
On the example (https://docusaurus-openapi.tryingpan.dev/petstore/update-pet-with-form) the sidebar items display the request type (POST, GET, etc.).
The docs at https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/README.md nor the example configuration at https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/docusaurus.config.js show how this sidebar configuration was achieved.
Document the configuration options for:
Due to the changes to DocItem this is no longer compatible with Docusaurus Beta22
Plugin works
Plugin errors because DocItemFooter no longer exists.
Install Beta22 and attempt to build or serve.
Cannot generate site - sidebar file generating incorrect document IDs for category/tag pages.
yarn build
should complete successfully.
The following error is seen:
Manually correcting the paths in the output directory's sidebar.js file fixed the issue until the docs are regenerated.
Documenting moderately complex REST APIs using json schemas.
Currently, there is no support for Response Headers. Potential solution would be to follow suit with Redoc, where the Response Headers renders above the Response Schema. See example below:
Currently we do not support displaying default values.
Add support for displaying default values when available, similar to ReDoc:
(Notice the "Default: 1" that is displayed under the property type and qualifier.)
n/a
n/a
When navigating from one API doc to another the selected language does not persist.
Ability to sync and persist the language choice across all API docs. For example, if a user chooses "Python" then the choice should be persisted locally and automatically selected when they move across API docs.
N/A
Ideally, I think we'd want to implement Docusaurus Tab synching but it might require refactoring language buttons into tabs.
https://docusaurus.io/docs/markdown-features/tabs#syncing-tab-choices
Today, there is no method for downloading the source OpenAPI specification file, for use "offline", e.g. Postman, Insomnia, SDK generation, some other doc tool, etc.
Ability to download a formatted, enriched copy of the OpenAPI spec for each set of API docs.
Linking to GitHub?
Single spec and multi should be "easy" since we can potentially just read them in, convert to postman collection, then back to OAS yaml
file. Micro-specs could be a challenge since each spec is a part of the whole.
This issue was opened by a bot called Community Health (PANW) because this repo has failed too many community health checks.
Repo maintainers: Please take the time to fix the issues in the table to reach the target score. These improvements will help others find your work and contribute to it. This issue will update as your score improves until it hits the target score.
Click More info for instructions to fix each item.
Health Check | Pass | Score | More Info |
---|---|---|---|
Contains a meaningful README.md file | โ | 20 / 20 | More info |
SUPPORT.md file exists | โ | 20 / 20 | More info |
Repo has a description | โ | 15 / 15 | More info |
Has a recognized open source license | โ | 15 / 15 | More info |
Has a descriptive repo name | โ | 15 / 15 | More info |
Required topics attached to repo | โ | 0 / 15 | More info |
CONTRIBUTING.md file with contribution guidelines | โ | 5 / 5 | More info |
Has custom issue and pull request templates | โ | 0 / 5 | More info |
Current score: 90
Target threshold: 100
Total possible: 110
There are no plans to introduce markdown/MDX support to generated-index
link descriptions. Many of our API specs contain markdown in their tag descriptions which leads to broken or unreadable text.
Allow support for generating tag doc pages with embedded index when categoryLinkSource
is set to "tag". This would also change the sidebar category link config type from generated-index
to doc
.
Considered opening a FR but Docusaurus maintainers explained that markdown link descriptions cannot be supported since they also double as meta description.
May need to come up with a naming convention for "tag docs", similar to info docs. Perhaps kebab-case the tag name
?
Today, syntax highlighting for API code samples is distinct from the syntax highlighting applied by Docusaurus.
Ideally, the syntax highlighting configured in docusaurus.config.js
would automatically be applied to the code samples (and possibly the live request payload/param editor).
Attempting to use CSS variables to match the style, which doesn't always work well.
One possible solution might be to adapt the Curl
theme component to use the built-in Docusaurus CodeBlock
component. I am not sure how we'd match styles with Monaco/VSCode editor, but it's possible we could pass the Docusaurus styles with prism-react-renderer
.
No way to execute queries from docs page right now since Execute button has been removed.
Noticed that Execute button for executing queries directly from the docs page used to be there but was removed from v18.0.0 onwards.
Bring back the query execution capability.
Right now I'm falling back to another older plugin of yours https://github.com/cloud-annotations/docusaurus-openapi
But this project's approach of generating mdx docs from Swagger is much more flexible since I can easily add additional md files for supplementary information and I'd like to switch to this. But the removal of the feature makes it a very difficult sell since my boss explicitly wants it :(
Users benefit greatly from being able to run queries from docs page rather than have to download Postman or use curl
The resolveJsonRefs
function is not properly called, which sets the resolved
variable value to a promise.
The function is async and should be preceded with the await
keyword.
The function is not properly called.
Add the await
keyword.
Currently there are gaps/inconsistencies in how --openapi-code-*
colors map to --ifm-color-*
colors. We are also missing a badge/color for the HEAD
method in the ApiDemoPanel
.
We should strive to keep colors consistent between docusaurus-theme-openapi-docs
and theme-classic
.
Cleanup colors.
Since #160 we are missing the Servers
component used for selecting the base URL for code samples.
Servers
component should normally appear above code samples section.
It's no longer visible.
Some elements in the ApiDemoPanel
cannot be accessed by keyboard/tab.
Apply tabindex: 0
to appropriate elements to ensure highest a11y experience.
n/a
Improving a11y not only improves UX but also helps improve SEO.
Carried over from #154
Currently there is no support for handling discriminators. Moreover, discriminator $ref pointers don't adhere to JSON Schema specification and are thus not resolved by our parser/resolver. This means we will need to resolve discriminator $ref pointers on-demand.
marginLeft
to "-2.4rem")OpenAPIParser
class byRef()
method to resolve $ref pointers. (Will require instantiating and passing a parser
instance for each spec we read in)Explored using oneOf
in place of discriminator but it renders the schema as a child of the property which does not satisfy the requirements.
ReDocly has a group write up on this and their ReDoc demo demonstrates the correct implementation: https://redocly.com/docs/resources/discriminator/
The Tabs
component included in docusaurus-theme-openapi-docs
directly conflicts with the one included in docusaurus-theme-classic
.
The components in docusaurus-theme-openapi-docs
should not affect components from other themes.
@theme/Tabs namespace collision
Consider renaming docusaurus-theme-openapi-docs
components in order to avoid potential namespace collisions with other themes. In this particular case, perhaps something like ResponseTabs
would suffice. Alternatively we could roll with something like ApiTabs
.
Tabs above should render like this: https://cortex.pan.dev/docs/data_lake/learn/about_cdl#region-base-urls
Some of the qualifiers, e.g minLength, maxLength, minItems, etc., result in mathematical expressions including operators like >, <, >=, <=
. The issue is that the expressions, although accurate, are not displayed in a natural, intuitive manner:
In the example below, notice the possible values are expressed in "reverse" as "1 โค value":
Refactor qualifiers as needed to display in a more natural, intuitive manner. For example, "1 <= value" could be more easily understood if it was written as "value >= 1" or simply ">= 1".
n/a
I believe ReDoc offers a great example of how to express qualifiers and should be referenced whenever needed.
If operations are grouped by tags (groupPathsBy: 'tags'
option) the operations are correctly grouped under individual tags but even if the tag has description it is nowhere to be found.
It would be perfect if the tag description could be used to generate index pages for individual tags.
The pages can be created manually if necessary such as this page: https://docusaurus-openapi.tryingpan.dev/api/food/burgers/introduction in the demo.
Happy to try and contribute if someone would please point me in the right directions ๐
In some cases, OpenAPI docs may be split into multiple micro-specs that, collectively, represent a single, logical API. In those cases, each micro-spec will come with its own info
section which will also generate a index.api.mdx
. When grouping paths by tag, this can lead to filename collisions as each subsequent index.api.mdx
file that is generated will overwrite the one prior.
The idea would be to extend support for the micro-spec use case by providing an option for defining when multiple specs should be treated as micro-specs and for creating a convention for generating unique "introduction" docs for each tagged group of paths. Additionally, sidebarOptions
should be extended to support setting the category link as the "introduction" doc for each respective group.
Longer term, it probably makes more sense to transition micro-specs into a mono-spec but there are some cases where this isn't possible or readily feasible.
Would be great to have the code snippets similar to stoplight. I'm also not seeing the 'Response' but perhaps that's a separate bug.
I've attached some images.
I'm trying to figure out how to theme it so it looks more similar to the screenshots. Haven't found a library that generates the client code yet.
Under most circumstances, the docusaurus-plugin-openapi-docs
plugin successfully reads, parses and generates MDX for a given OpenAPI specification. Still, there are times when processing errors occur, due to gaps or incompatibilities, which can lead to exceptions. These errors can occur for a number of reasons at a number of points during processing, including:
Focusing more on validating the OAS outside of the plugin using various linters, extensions, tools, etc.
Improvements in this area would greatly enhance the usability of the plugin while also decreasing the time needed to diagnose failures and deliver fixes.
[ERROR] TypeError: Cannot read properties of undefined (reading 'default')
When implementing versioning, it's easy for a user to forget or overlook which version of an API doc they are looking at. The existing versioning system provides a version dropdown selector but individual API docs lack the context necessary to label what API version it applies to.
An API doc "version context switcher" component that can be used to:
Example:
A component like the one above could possibly fit in the upper-right of each API doc item, above the ApiDemoPanel
section. Preferable using the built-in Infima Tabs
or Button
components.
The current version should be in the active
state. The other versions should only be displayed if the endpoint is actually supported in those versions. The latter will likely require an extended API versions metadata object/file to allow for quick lookup and conditional rendering of supported versions.
Not worrying about it. We already have a dropdown selector and version badge in the sidebar.
Will share third-party examples of this use case if I find any!
This seems not to read the x-codesample
from the API spec but is instead generating it's own code examples. So can we hook into that to add, for example, PowerShell examples?
Currently, we include only the info title, description and version badge.
Ideally, we would also include any remaining fields, e.g. support contact, support URL, terms of service, license. See the following for more details: https://swagger.io/docs/specification/api-general-info/
N/A
Feel free to format as needed for optimal display.
No
Today, we can group by tag for multiple spec files within the same directory. It would be nice to have the ability to group a set of those spec files together in one parent category instead of having to define separate APIs in the config.
Add a x-parent-category
option to the spec file(s) that includes a Summary (display in the sidebar) . With that option, a sidebar category would be created and the items of that sidebar category would be a concatenation of the sidebar categories for each tag in each spec file that shares the x-parent-category
.
A simplified example:
I have spec files for my shop named Apple, Banana, Double Shot, Latte, Cortado . In Apple, all endpoints are tagged Apple
, in Banana all are tagged Banana
, etc... I would create a x-parent-category
: "Fruits" which would be added to the Apple and Banana spec files. The generated Sidebar would then have a top level category: Fruits with items that is an array of the Apple sidebar category and Banana sidebar category. The same thing would happen for x-parent-category
of Espresso Drinks
We'd See on the sidebar:
Fruits โผ
Apple โผ
Banana โผ
Espresso Drinks โผ
Double Shot โผ
Double Shot โผ
Cortado โผ
The main difference between what is there today would be that if x-parent-category
was specified the generated sidebar would add the higher level category. If no x-parent-category
is specified, there would be no difference in the output.
Currently, there is no documentation on how to make method labels/badges appear next to API items in the sidebar.
Document the steps necessary for enabling them.
Running npm run build
returns a lot of:
[ERROR] Docusaurus server-side rendering could not render static page with path /api/petstore/category/...
ReactContextError
It should build a static website.
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Home/common/temp/node_modules/.pnpm/@[email protected]_818345a8d7cf6af82aae687b15f8b782/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Home/common/temp/node_modules/.pnpm/[email protected]/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Home/common/temp/node_modules/.pnpm/[email protected]/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
Docusaurus: 2.0.0-rc.1
OpenAPI-docs: 1.1.1
Using pnpm and rush.
Part of docusaurus.config:
[
'docusaurus-plugin-openapi-docs',
{
id: 'petstore',
docsPluginId: 'apiPetstore',
config: {
petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
specPath: 'static/api/v1.yaml', // Path to designated spec file
outputDir: 'docs/api/petstore', // Output directory for generated .mdx docs
sidebarOptions: {
groupPathsBy: 'tag',
sidebarCollapsible: true,
sidebarCollapsed: true,
},
},
}
},
],
[
'@docusaurus/plugin-content-docs',
{
path: 'docs/api/petstore',
routeBasePath: '/api/petstore',
id: 'apiPetstore',
sidebarPath: require.resolve('./sidebars/petstore.js'),
sidebarCollapsible: false,
docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/ApiItem',
},
],
plugins.js
const { ProvidePlugin } = require('webpack');
const path = require('path');
const tailwindPlugin = (context, options) => {
return {
name: 'tailwind-plugin',
configurePostCss(postcssOptions) {
postcssOptions.plugins = [
require('postcss-import'),
require('tailwindcss/nesting'),
require('tailwindcss'),
require('autoprefixer'),
];
return postcssOptions;
},
};
};
const webpackPlugin = (context, options) => {
return {
name: 'webpack-plugin',
configureWebpack(config) {
return {
module: {
rules: [
{
test: /\.m?js/,
resolve: {
fullySpecified: false,
},
},
],
},
plugins: [
new ProvidePlugin({
process: require.resolve('process/browser'),
}),
],
resolve: {
fallback: {
},
alias: {
},
},
};
},
};
};
module.exports = { tailwindPlugin, webpackPlugin };
Is there any way to get more debug information than just ReactContextError?
Currently, docs produced from multiple specs are written to the same directory and directory level. This presents issue when organizing and/or constructing sidebars for different APIs.
An organization strategy for handling multi-specs. For example:
info.title
*.sidebar.js
slices for each APIgroupPathsBy: 'file'
to sidebarOptions
Manually constructing the sidebar object can be a painful experience for medium to large APIs.
autogenerated
and __category__.json
sidebar.js
for multiple APIs, each API should be grouped by category label. We would need to decide what label to use or where to derive it from, e.g. kebab-cased info.title
?Paginator is sometimes not rendering when cycling through endpoints via the sidebar. It seems to always appear on initial page load but not on history change.
Paginator should appear for every API doc, regardless of how a user navigates to it.
Investigate this block of code: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/panw-main/packages/docusaurus-theme-openapi/src/theme/ApiItem/index.tsx#L35
Replicate using https://docusaurus-openapi.tryingpan.dev/
Using groupPathsby: "tags"
on a spec with no tags results in the following error:
[ERROR] TypeError: Cannot read properties of undefined (reading 'includes')
A spec with no tags should use a fallback "UNTAGGED" grouping to handle grouping paths.
See error above.
Reinstate the UNTAGGED
group and add additional checks to determine if tags exist before proceeding.
The authorization form is empty for the authentication-required paths.
An authorization form with the required header for passing the security parameter.
The authorization form is empty.
{
"openapi": "3.0.1",
"info": {
"title": "Test",
"description": "Description",
"termsOfService": "",
"contact": {
"email": ""
},
"version": "1.1.0"
},
"externalDocs": {
"description": "Find out more about Swagger",
"url": "http://swagger.io"
},
"servers": [
{
"url": "https://api.test.url"
}
],
"paths": {
"/test": {
"post": {
"summary": "test endpoint",
"operationId": "opt1",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"required": [
"id"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "id-uuid"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestResp"
}
}
}
}
},
"security": [
{
"TestAuth": []
}
]
}
}
},
"components": {
"schemas": {
"TestResp": {
"required": [
"id",
"name"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "id-uuid"
},
"name": {
"type": "string",
"description": "test name"
}
}
}
},
"securitySchemes": {
"TestAuth": {
"type": "apiKey",
"name": "X-Test-Auth-Key",
"in": "header"
}
}
}
}
npm run start
I'm trying to generate the document website from an OpenAPI JSON spec. the authentication method and details are ignored in the compiled version. no authorization form or detail is rendered.
This issue was opened by a bot called Community Health (PANW) because this repo has failed too many community health checks.
Repo maintainers: Please take the time to fix the issues in the table to reach the target score. These improvements will help others find your work and contribute to it. This issue will update as your score improves until it hits the target score.
Click More info for instructions to fix each item.
Health Check | Pass | Score | More Info |
---|---|---|---|
Contains a meaningful README.md file | โ | 20 / 20 | More info |
SUPPORT.md file exists | โ | 20 / 20 | More info |
Repo has a description | โ | 15 / 15 | More info |
Has a recognized open source license | โ | 15 / 15 | More info |
Has a descriptive repo name | โ | 15 / 15 | More info |
Required topics attached to repo | โ | 0 / 15 | More info |
CONTRIBUTING.md file with contribution guidelines | โ | 5 / 5 | More info |
Has custom issue and pull request templates | โ | 0 / 5 | More info |
Current score: 90
Target threshold: 100
Total possible: 110
There are some product APIs that generate a unique base URL per customer/tenant, which is not something we could know or predict ahead of time.
The ability for users to manually type in their API base URL (server).
n/a
Generated code samples directly reference the base URL. One consideration would be how to persist the custom base URL throughout the session or in localStorage
.
In some cases, certain API's require multiple security schemes for authentication. As of now, the current <SecuritySchemes />
component only supports a single security scheme render.
There should be unique keys for each security scheme element to rid of any React warnings in the console. In addition, the "Authorization:" title is repeated for each Security Scheme and should be refactored and restyled to only render once.
React related console warnings for duplicate keys and repeated "Authorization: " title.
Handling the duplicate keys should be straight-forward. As for the repeated "Authorization: " title, the <SecuritySchemes />
component can be refactored in a manner that renders a list and a single "Authorization: " title (for API's that require multiple security schemes)
This page crashed.
Hook useTabGroupChoice is called outside the .
Page should load.
Page crashes with above message.
Docusaurus 2.0.0-rc.1, Open API 0.0.0-396
Have cleared and rebuilt API documentation using 396 canary.
Currently, the plugin does not support documenting webhooks.
Introduce webhook support, similar to how ReDoc currently handles them:
Not supporting them, since none of our current product APIs include them.
OpenAPI 3.1 will make paths
optional, which will be another way to imply/support webhook endpoints. To support them today (3.0) I believe we'd have to use vendor extensions:
x-webhooks:
newPet:
post:
summary: New pet
description: Information about a new pet in the systems
operationId: newPet
tags:
- pet
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
description: Return a 200 status to indicate that the data was received successfully
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.