docusaurus-plugin-openapi-docs 0.0.0-616 → 0.0.0-618

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +73 -62
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -22,12 +22,42 @@ The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with com
22
22
 
23
23
  Key Features:
24
24
 
25
- - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
25
+ - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0.
26
26
  - **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
27
27
  - **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
28
- - **Capable:** Supports single, multi and _even micro_ OpenAPI specs.
28
+ - **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
29
29
 
30
- ## Installation
30
+ ## Compatibility Matrix
31
+
32
+ | Docusaurus OpenAPI Docs | Docusaurus |
33
+ | ----------------------- | --------------- |
34
+ | 1.x.x | `2.0.1 - 2.2.0` |
35
+ | 2.x.x (beta) | `2.3.0 - 2.4.0` |
36
+
37
+ ## Bootstrapping from Template (new Docusaurus site)
38
+
39
+ Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
40
+
41
+ ```bash
42
+ npx create-docusaurus@2.2.0 my-website --package-manager yarn
43
+ ```
44
+
45
+ > When prompted to select a template choose `Git repository`.
46
+
47
+ Template Repository URL:
48
+
49
+ ```bash
50
+ https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
51
+ ```
52
+
53
+ > When asked how the template repo should be cloned choose "copy" (unless you know better).
54
+
55
+ ```bash
56
+ cd my-website
57
+ yarn start
58
+ ```
59
+
60
+ ## Installation (existing Docusaurus site)
31
61
 
32
62
  Plugin:
33
63
 
@@ -41,53 +71,57 @@ Theme:
41
71
  yarn add docusaurus-theme-openapi-docs
42
72
  ```
43
73
 
74
+ ## Compatibility Matrix
75
+
76
+ | Docusaurus OpenAPI Docs | Docusaurus |
77
+ | ----------------------- | ---------------- |
78
+ | 1.x.x | `>=2.0.1 <2.3.0` |
79
+ | 2.x.x (beta) | `>=2.3.0 <2.4.1` |
80
+
44
81
  ## Configuring `docusaurus.config.js` (Plugin and theme usage)
45
82
 
46
- Here is an example of properly configuring your `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
83
+ Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
47
84
 
48
85
  ```js
49
86
  // docusaurus.config.js
50
87
 
51
88
  {
52
89
  presets: [
53
- [
54
- "classic",
55
- /** @type {import('@docusaurus/preset-classic').Options} */
56
- ({
57
- docs: {
58
- sidebarPath: require.resolve("./sidebars.js"),
59
- // Please change this to your repo.
60
- // Remove this to remove the "edit this page" links.
61
- editUrl:
62
- "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
63
- docLayoutComponent: "@theme/DocPage",
64
- docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs
65
- },
66
- blog: {
67
- showReadingTime: true,
68
- // Please change this to your repo.
69
- // Remove this to remove the "edit this page" links.
70
- editUrl:
71
- "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
72
- },
73
- theme: {
74
- customCss: require.resolve("./src/css/custom.css")
75
- }
76
- })
77
- ]
78
- ],
90
+ [
91
+ "classic",
92
+ /** @type {import('@docusaurus/preset-classic').Options} */
93
+ ({
94
+ docs: {
95
+ sidebarPath: require.resolve("./sidebars.js"),
96
+ editUrl:
97
+ "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
98
+ docLayoutComponent: "@theme/DocPage",
99
+ docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
100
+ },
101
+ blog: {
102
+ showReadingTime: true,
103
+ editUrl:
104
+ "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
105
+ },
106
+ theme: {
107
+ customCss: require.resolve("./src/css/custom.css")
108
+ }
109
+ })
110
+ ]
111
+ ],
79
112
 
80
113
  plugins: [
114
+ [
81
115
  'docusaurus-plugin-openapi-docs',
82
116
  {
83
- id: "apiDocs",
84
- docsPluginId: "classic",
117
+ id: "api", // plugin id
118
+ docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
85
119
  config: {
86
- petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
87
- specPath: "examples/petstore.yaml", // Path to designated spec file
88
- outputDir: "api/petstore", // Output directory for generated .mdx docs
89
- sidebarOptions: {
90
- groupPathsBy: "tag",
120
+ petstore: { // the <id> referenced when running CLI commands
121
+ specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
122
+ outputDir: "api/petstore", // output directory for generated files
123
+ sidebarOptions: { // optional, instructs plugin to generate sidebar.js
124
+ groupPathsBy: "tag", // group sidebar items by operation "tag"
91
125
  },
92
126
  },
93
127
  burgers: {
@@ -98,7 +132,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
98
132
  },
99
133
  ]
100
134
  ],
101
- themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other components
135
+ themes: ["docusaurus-theme-openapi-docs"], // export theme components
102
136
  }
103
137
  ```
104
138
 
@@ -110,7 +144,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
110
144
 
111
145
  | Name | Type | Default | Description |
112
146
  | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
113
- | `id` | `string` | `null` | A unique document id. |
147
+ | `id` | `string` | `null` | A unique plugin id. |
114
148
  | `docsPluginId` | `string` | `null` | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
115
149
 
116
150
  ### config
@@ -256,29 +290,6 @@ yarn docusaurus gen-api-docs:version petstore:all
256
290
 
257
291
  > Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
258
292
 
259
- ## Installing from Template
260
-
261
- Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
262
-
263
- ```bash
264
- npx create-docusaurus@2.0.1 my-website --package-manager yarn
265
- ```
266
-
267
- > When prompted to select a template choose `Git repository`.
268
-
269
- Template Repository URL:
270
-
271
- ```bash
272
- https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
273
- ```
274
-
275
- > When asked how the template repo should be cloned choose "copy" (unless you know better).
276
-
277
- ```bash
278
- cd my-website
279
- yarn
280
- ```
281
-
282
293
  ## Developer Quick Start
283
294
 
284
295
  > Looking to make a contribution? Make sure to checkout out our contributing guide.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "docusaurus-plugin-openapi-docs",
3
3
  "description": "OpenAPI plugin for Docusaurus.",
4
- "version": "0.0.0-616",
4
+ "version": "0.0.0-618",
5
5
  "license": "MIT",
6
6
  "keywords": [
7
7
  "openapi",
@@ -68,5 +68,5 @@
68
68
  "engines": {
69
69
  "node": ">=14"
70
70
  },
71
- "gitHead": "8ba8a83ca6b3bd116a0a2bab85594d719b76b749"
71
+ "gitHead": "783cd742f2f53696330c17c38aa9087a5e83fc95"
72
72
  }