@synx-ai/oas3-mdx - npm Package Compare versions

Comparing version 0.3.5 to 0.3.12

dist/bundler.js

@@ -1,2 +0,1 @@
-"use_strict";
 "use strict";
@@ -45,4 +44,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
     return new Promise((resolve, reject) => {
-        if (url.startsWith("http:")) {
-            http
+        if (url.startsWith("http")) {
+            let protocol = url.startsWith("https:") ? https : http;
+            protocol
                 .get(url, (res) => {
@@ -53,9 +53,2 @@ handleHTTPResponse(url, res, resolve, reject);
         }
-        else if (url.startsWith("https:")) {
-            https
-                .get(url, (res) => {
-                handleHTTPResponse(url, res, resolve, reject);
-            })
-                .on("error", reject);
-        }
         else {
@@ -62,0 +55,0 @@ reject("Protocol not supported.");

dist/cli.js

@@ -38,2 +38,8 @@ #!/usr/bin/env node
 })
+    .option("parser", {
+    alias: "p",
+    describe: "prettier parser",
+    type: "string",
+    default: "mdx",
+})
     .help().argv;
@@ -43,4 +49,5 @@ // call the convert function from ./index.js
     outPath: path.resolve(process.cwd(), argv.target),
-    templatePath: path.resolve(argv.templates),
+    templatesPath: path.resolve(argv.templates),
     snippetTargets: argv.snippets.split(","),
+    prettierParser: argv.parser,
 })
@@ -47,0 +54,0 @@ .then(() => {

dist/index.d.ts

@@ -5,5 +5,7 @@ declare type Optional = {
     /** @default "../templates/" */
-    templatePath?: string;
+    templatesPath?: string;
     /** @default ["curl"] */
     snippetTargets?: string[];
+    /** @default "../templates/" */
+    prettierParser?: string;
 };
@@ -14,3 +16,3 @@ /**
  * @param   {string}    outPath path to write documents
- * @param   {string}    templatePath path to markdown templates
+ * @param   {string}    templatesPath path to markdown templates
  * @returns {Promise<void>}
@@ -17,0 +19,0 @@ */

dist/index.js

@@ -1,2 +0,1 @@
-"use_strict";
 "use strict";
@@ -59,3 +58,3 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @param   {string}    outPath path to write documents
- * @param   {string}    templatePath path to markdown templates
+ * @param   {string}    templatesPath path to markdown templates
  * @returns {Promise<void>}
@@ -65,3 +64,3 @@ */
     return new Promise((resolve, reject) => {
-        const { outPath = path.resolve(process.cwd(), "./build"), templatePath = "../templates/", snippetTargets = ["shell"], } = options;
+        const { outPath = path.resolve(process.cwd(), "./build"), templatesPath = "../templates/", snippetTargets = ["shell"], prettierParser = "mdx", } = options;
         try {
@@ -90,3 +89,3 @@ // load the spec from a json into an object
                     if (key.toLowerCase().includes("xml")) {
-                        const name = Object.prototype.hasOwnProperty.call(context, "xml") ? context.xml.name : "item";
+                        const name = Object.prototype.hasOwnProperty.call(context, "xml") ? context.xml.name : "Data";
                         return xmlCodeBlock(name, sampler(), title);
@@ -106,7 +105,7 @@ }
                 let pathTemplate;
-                if (fs.existsSync(path.resolve(process.cwd(), templatePath, "path.hdb"))) {
-                    pathTemplate = Handlebars.compile(fs.readFileSync(path.resolve(process.cwd(), templatePath, "path.hdb"), "utf8"));
+                if (fs.existsSync(path.resolve(process.cwd(), templatesPath, "path.hdb"))) {
+                    pathTemplate = Handlebars.compile(fs.readFileSync(path.resolve(process.cwd(), templatesPath, "path.hdb"), "utf8"));
                 }
-                else if (fs.existsSync(path.resolve(__dirname, templatePath, "path.hdb"))) {
-                    pathTemplate = Handlebars.compile(fs.readFileSync(path.resolve(__dirname, templatePath, "path.hdb"), "utf8"));
+                else if (fs.existsSync(path.resolve(__dirname, templatesPath, "path.hdb"))) {
+                    pathTemplate = Handlebars.compile(fs.readFileSync(path.resolve(__dirname, templatesPath, "path.hdb"), "utf8"));
                 }
@@ -123,18 +122,21 @@ else {
                         const method = apiPath[methodKey];
-                        // generate snippets for this endpoint
-                        const generatedCode = OpenAPISnippet.getEndpointSnippets(spec, pathKey, methodKey, snippetTargets);
-                        Object.values(generatedCode.snippets).forEach((snippet) => {
-                            const { id } = snippet;
-                            snippet.lang = id.split("_")[0].replace("node", "javascript");
-                        });
-                        // render the path using Handlebars and save it
-                        fs.writeFileSync(`${outPath}${pathKey}/${methodKey}.md`, prettier.format(pathTemplate({
-                            slug: _.kebabCase(`${pathKey}-${methodKey}`),
-                            path: pathKey,
-                            httpMethod: _.toUpper(methodKey),
-                            method: method,
-                            snippets: generatedCode.snippets,
-                        }), {
-                            parser: "markdown",
-                        }));
+                        // see if this method isn't ignored
+                        if (!Object.prototype.hasOwnProperty.call(method, "x-docgenIgnore")) {
+                            // generate snippets for this endpoint
+                            const generatedCode = OpenAPISnippet.getEndpointSnippets(spec, pathKey, methodKey, snippetTargets);
+                            Object.values(generatedCode.snippets).forEach((snippet) => {
+                                const { id } = snippet;
+                                snippet.lang = id.split("_")[0].replace("node", "javascript");
+                            });
+                            // render the path using Handlebars and save it
+                            fs.writeFileSync(`${outPath}${pathKey}/${methodKey}.md`, prettier.format(pathTemplate({
+                                slug: _.kebabCase(`${pathKey}-${methodKey}`),
+                                path: pathKey,
+                                httpMethod: _.toUpper(methodKey),
+                                method: method,
+                                snippets: generatedCode.snippets,
+                            }), {
+                                parser: prettierParser,
+                            }));
+                        }
                     });
@@ -141,0 +143,0 @@ });

package.json

 {
   "name": "@synx-ai/oas3-mdx",
-  "version": "0.3.5",
+  "version": "0.3.12",
   "description": "Convert OpenAPI spec to Markdown files.",
@@ -54,2 +54,3 @@ "main": "dist/index.js",
   "devDependencies": {
+    "@types/jest": "^26.0.20",
     "@types/node": "^14.14.31",
@@ -66,2 +67,3 @@ "@typescript-eslint/eslint-plugin": "^4.15.2",
     "pinst": "^2.1.6",
+    "speccy": "^0.11.0",
     "ts-jest": "^26.5.2",
@@ -68,0 +70,0 @@ "typescript": "^4.1.5"

readme.md

@@ -14,3 +14,3 @@ # OpenAPI3 to Markdown converter
 ```console
-yarn add @synx-ai/openapi2md
+yarn add @synx-ai/oas3-mdx
 ```
@@ -20,3 +20,3 @@
 ```console
-npm install @synx-ai/openapi2md
+npm install @synx-ai/oas3-mdx
 ```
@@ -27,15 +27,5 @@
 
-### Options
-
-| Option             | CLI argument | JavaScript parameter | Default       |
-| ------------------ | ------------ | -------------------- | ------------- |
-| `OpenAPI spec`     | --spec       | specFile             | _None_        |
-| `Target build dir` | --target     | outPath              | `./build`     |
-| `Templates dir`    | --templates  | templatePath         | `./templates` |
-
-The tool will try to load the `--templates` relative to current working path first, then will fallback to library path.
-
 ### CLI
 ```console
-Usage: openapi2md --specs [file] --target [target path] --templates [template path]
+Usage: oas3-mdx --specs [file] --target [target path] --templates [template path] --snippets [string with targets]
 
@@ -46,3 +36,4 @@ Options:
   -o, --target    target build path                [default: "./build"]
-  -t, --template  templates paths              [default: "./templates"]
+  -t, --templates templates path               [default: "./templates"]
+  -c, --snippets  comma separated targets            [default: "shell"]
       --help      Show help
@@ -55,5 +46,68 @@ ```
 
-convert('./example/petstore.json', './build');
+// optional arguments are expected as an object, ie:
+convert('./example/petstore.json' /*, { outPath: 'my_path' }*/);
 ```
 
+### Options
+
+| Option             | CLI argument | JavaScript parameter | Default       |
+| ------------------ | ------------ | -------------------- | ------------- |
+| `OpenAPI spec`     | --spec       | specFile             | _None_        |
+| `Target build dir` | --target     | outPath              | `./build`     |
+| `Templates dir`    | --templates  | templatesPath        | `./templates` |
+| `Snippet targets`  | --snipetts   | snippetTargets       | `["shell"]`   |
+| `Prettier parser`  | --parser     | prettierParser       | `mdx`         |
+
+The tool will try to load the `--templates` relative to current working path first, then will fallback to library path.
+
+### Valid Snippet Targets
+Currently, OpenAPI Snippet supports the following targets from [HTTP Snippet](https://github.com/Kong/httpsnippet) library:
+
+* `c_libcurl` (default)
+* `csharp_restsharp` (default)
+* `go_native` (default)
+* `java_okhttp`
+* `java_unirest` (default)
+* `javascript_jquery`
+* `javascript_xhr` (default)
+* `node_native` (default)
+* `node_request`
+* `node_unirest`
+* `objc_nsurlsession` (default)
+* `ocaml_cohttp` (default)
+* `php_curl` (default)
+* `php_http1`
+* `php_http2`
+* `python_python3` (default)
+* `python_requests`
+* `ruby_native` (default)
+* `shell_curl` (default)
+* `shell_httpie`
+* `shell_wget`
+* `swift_nsurlsession` (default)
+
+### Prettier Parser
+
+For the parser, while `mdx` or `markdown` are suggested, you can use anything supported by [Prettier](https://prettier.io/docs/en/options.html#parser).
+
+
+### Custom Tags on Schema
+
+- `x-docgenIgnore`: at method level to ignore output generation, for example:
+
+```js
+{
+  ...
+  "paths": {
+    "/pet": {
+      "put": { // this method will be ignored
+        "x-docgenIgnore": true,
+        "summary": "Update an existing pet",
+        ...
+      }
+    }
+  }
+}
+```
+
 ### Templates
@@ -76,3 +130,17 @@
 ```
+## Troubleshooting
+- Most common errors happens due a malformed file, to validate and lint your spec for possible errors check [Speccy](https://github.com/wework/speccy).
+- If your specification has multiple paths which map to the same OpenAPI path, you can should set `"x-hasEquivalentPaths": true,` on the root object, example:
 
+```javascript
+{
+  "openapi": "3.0.2",
+  "x-hasEquivalentPaths": true,
+  "info": {
+    ...
+  }
+  ...
+}  
+```
+
 ## Roadmap
@@ -79,0 +147,0 @@ - [X] Create a cli.js file to execute commands using yarn or npm

No alert changes

Improved metrics

Total package byte prevSize

35244

increased by7.36%

Lines of code

402

increased by1.01%

Number of lines in readme file

148

increased by85%

Worsened metrics

Dev dependency count

15

increased by15.38%

No dependency changes