docusaurus-plugin-openapi-docs 0.0.0-617 → 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 +65 -61
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -25,9 +25,39 @@ Key Features:
25
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
 
@@ -50,51 +80,48 @@ yarn add docusaurus-theme-openapi-docs
50
80
 
51
81
  ## Configuring `docusaurus.config.js` (Plugin and theme usage)
52
82
 
53
- 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.
54
84
 
55
85
  ```js
56
86
  // docusaurus.config.js
57
87
 
58
88
  {
59
89
  presets: [
60
- [
61
- "classic",
62
- /** @type {import('@docusaurus/preset-classic').Options} */
63
- ({
64
- docs: {
65
- sidebarPath: require.resolve("./sidebars.js"),
66
- // Please change this to your repo.
67
- // Remove this to remove the "edit this page" links.
68
- editUrl:
69
- "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
70
- docLayoutComponent: "@theme/DocPage",
71
- docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs
72
- },
73
- blog: {
74
- showReadingTime: true,
75
- // Please change this to your repo.
76
- // Remove this to remove the "edit this page" links.
77
- editUrl:
78
- "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
79
- },
80
- theme: {
81
- customCss: require.resolve("./src/css/custom.css")
82
- }
83
- })
84
- ]
85
- ],
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
+ ],
86
112
 
87
113
  plugins: [
114
+ [
88
115
  'docusaurus-plugin-openapi-docs',
89
116
  {
90
- id: "apiDocs",
91
- docsPluginId: "classic",
117
+ id: "api", // plugin id
118
+ docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
92
119
  config: {
93
- petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
94
- specPath: "examples/petstore.yaml", // Path to designated spec file
95
- outputDir: "api/petstore", // Output directory for generated .mdx docs
96
- sidebarOptions: {
97
- 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"
98
125
  },
99
126
  },
100
127
  burgers: {
@@ -105,7 +132,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
105
132
  },
106
133
  ]
107
134
  ],
108
- themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other components
135
+ themes: ["docusaurus-theme-openapi-docs"], // export theme components
109
136
  }
110
137
  ```
111
138
 
@@ -117,7 +144,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
117
144
 
118
145
  | Name | Type | Default | Description |
119
146
  | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
120
- | `id` | `string` | `null` | A unique document id. |
147
+ | `id` | `string` | `null` | A unique plugin id. |
121
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"). |
122
149
 
123
150
  ### config
@@ -263,29 +290,6 @@ yarn docusaurus gen-api-docs:version petstore:all
263
290
 
264
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.
265
292
 
266
- ## Installing from Template
267
-
268
- Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
269
-
270
- ```bash
271
- npx create-docusaurus@2.0.1 my-website --package-manager yarn
272
- ```
273
-
274
- > When prompted to select a template choose `Git repository`.
275
-
276
- Template Repository URL:
277
-
278
- ```bash
279
- https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
280
- ```
281
-
282
- > When asked how the template repo should be cloned choose "copy" (unless you know better).
283
-
284
- ```bash
285
- cd my-website
286
- yarn
287
- ```
288
-
289
293
  ## Developer Quick Start
290
294
 
291
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-617",
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": "497549c580de64c1df8b91e6b7a7f283e8defb85"
71
+ "gitHead": "783cd742f2f53696330c17c38aa9087a5e83fc95"
72
72
  }