docusaurus-plugin-openapi-docs 0.0.0-617 → 0.0.0-619

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 -68
  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
 
@@ -41,60 +71,50 @@ Theme:
41
71
  yarn add docusaurus-theme-openapi-docs
42
72
  ```
43
73
 
44
- ## Compatibility Matrix
45
-
46
- | Docusaurus OpenAPI Docs | Docusaurus |
47
- | ----------------------- | ---------------- |
48
- | 1.x.x | `>=2.0.1 <2.3.0` |
49
- | 2.x.x (beta) | `>=2.3.0 <2.4.1` |
50
-
51
74
  ## Configuring `docusaurus.config.js` (Plugin and theme usage)
52
75
 
53
- Here is an example of properly configuring your `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
76
+ Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
54
77
 
55
78
  ```js
56
79
  // docusaurus.config.js
57
80
 
58
81
  {
59
82
  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
- ],
83
+ [
84
+ "classic",
85
+ /** @type {import('@docusaurus/preset-classic').Options} */
86
+ ({
87
+ docs: {
88
+ sidebarPath: require.resolve("./sidebars.js"),
89
+ editUrl:
90
+ "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
91
+ docLayoutComponent: "@theme/DocPage",
92
+ docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
93
+ },
94
+ blog: {
95
+ showReadingTime: true,
96
+ editUrl:
97
+ "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
98
+ },
99
+ theme: {
100
+ customCss: require.resolve("./src/css/custom.css")
101
+ }
102
+ })
103
+ ]
104
+ ],
86
105
 
87
106
  plugins: [
107
+ [
88
108
  'docusaurus-plugin-openapi-docs',
89
109
  {
90
- id: "apiDocs",
91
- docsPluginId: "classic",
110
+ id: "api", // plugin id
111
+ docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
92
112
  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",
113
+ petstore: { // the <id> referenced when running CLI commands
114
+ specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
115
+ outputDir: "api/petstore", // output directory for generated files
116
+ sidebarOptions: { // optional, instructs plugin to generate sidebar.js
117
+ groupPathsBy: "tag", // group sidebar items by operation "tag"
98
118
  },
99
119
  },
100
120
  burgers: {
@@ -105,7 +125,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
105
125
  },
106
126
  ]
107
127
  ],
108
- themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other components
128
+ themes: ["docusaurus-theme-openapi-docs"], // export theme components
109
129
  }
110
130
  ```
111
131
 
@@ -117,7 +137,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
117
137
 
118
138
  | Name | Type | Default | Description |
119
139
  | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
120
- | `id` | `string` | `null` | A unique document id. |
140
+ | `id` | `string` | `null` | A unique plugin id. |
121
141
  | `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
142
 
123
143
  ### config
@@ -263,29 +283,6 @@ yarn docusaurus gen-api-docs:version petstore:all
263
283
 
264
284
  > 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
285
 
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
286
  ## Developer Quick Start
290
287
 
291
288
  > 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-619",
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": "1612ad3eee17e99fa5bad3bd2be5bf4cb079a5a2"
72
72
  }