improved samples

example/build/md/users/get.md

@@ -0,0 +1,60 @@
+---
+id:
+slug: users-get
+---
+
+```
+GET /users
+```
+
+**Returns a list of users.: **Optional extended description in CommonMark or HTML.
+
+## Parameters
+
+| name | in  | type | required | description |
+| ---- | --- | ---- | -------- | ----------- |
+
+## Code Snippets
+
+```javascript title="Node + Native"
+const http = require("http");
+
+const options = {
+  method: "GET",
+  hostname: "api.example.com",
+  port: null,
+  path: "/v1/users",
+  headers: {},
+};
+
+const req = http.request(options, function (res) {
+  const chunks = [];
+
+  res.on("data", function (chunk) {
+    chunks.push(chunk);
+  });
+
+  res.on("end", function () {
+    const body = Buffer.concat(chunks);
+    console.log(body.toString());
+  });
+});
+
+req.end();
+```
+
+## Responses
+
+### 200
+
+A JSON array of user names
+
+| Headers      |                  |
+| ------------ | ---------------- |
+| content-type | application/json |
+
+**Example `response` for `application/json`**
+
+```json
+["string"]
+```

example/build/mdx/users/get.md

@@ -0,0 +1,52 @@
+---
+id: getUsers
+title: Returns a list of users.
+---
+
+<!-- prettier-ignore-start -->
+
+export const Method = ({children, color}) => (
+  <span
+    style={{
+      backgroundColor: color,
+      borderRadius: '6px',
+      color: '#fff',
+      padding: '0.6rem 1.2rem',
+      textTransform: 'uppercase',
+      fontWeight: 'bold'
+    }}>
+    {children}
+  </span>
+);
+
+export const Path = ({children}) => (
+  <span
+    style={{
+      borderRadius: '6px',
+      color: '#000',
+      paddingLeft: '0.8rem',
+      textTransform: 'lowercase',
+      fontWeight: 'bold',
+      fontsSize: '1.2rem'
+    }}>
+    {children}
+  </span>
+);
+
+export const Url = ({children}) => {
+  return (
+    <div
+      style={{
+        marginBottom: '3rem',
+        paddingTop: '1rem'
+      }}>
+      {children}
+    </div>
+  );
+};
+
+<!-- prettier-ignore-end -->
+
+<Url>
+  <Method color="#6b55b2">GET</Method><Path>{unescape(escape('/users'))}</Path>
+</Url>

example/index.js

@@ -1,21 +1,40 @@
-const convert = require('../dist').default;
-const bundler = require('../dist/bundler').default;
-const OpenAPISampler = require('openapi-sampler');
+const convert = require("../dist").default;
 
-console.log(process.cwd())
-/*
-bundler('example/petstore.json', './')
-  .then(spec => {
-    //console.log(OpenAPISampler.sample(spec.components.schemas.Pet, {}, spec));
+// converts to markdown using default template
+convert("example/specs/simple.yaml", {
+  outPath: "./example/build/md",
+  snippetTargets: ["node"],
+  prettierParser: "markdown",
+})
+  .then(() => {
+    console.log(`File 'example/specs/simple.yaml' converted to markdown.`);
   })
-  .catch(err => {
+  .catch((err) => {
     console.error(err);
-  })*/
+  });
 
-convert('example/petstore.json', { outPath: './build', snippetTargets: ["node", "python"] })
+// converts to mdx using default template
+convert("example/specs/simple.yaml", {
+  outPath: "./example/build/mdx",
+  snippetTargets: ["shell", "python"],
+  templatesPath: "example/templates/mdx",
+  prettierParser: "markdown",
+})
   .then(() => {
-    console.log("Finished.")
+    console.log(`File 'example/specs/simple.yaml' converted to mdx.`);
   })
-  .catch(err => {
+  .catch((err) => {
     console.error(err);
+  });
+
+// converts a complex file
+convert("example/specs/petstore.json", {
+  outPath: "./build",
+  snippetTargets: ["node", "python"]
+})
+  .then(() => {
+    console.log("Finished.");
   })
+  .catch((err) => {
+    console.error(err);
+  });

example/petstore.json → example/specs/petstore.json

@@ -20,7 +20,7 @@
   },
   "servers": [
     {
-      "url": "/api/v3"
+      "url": "http://swagger.io/api/v3"
     }
   ],
   "tags": [

example/specs/simple.yaml

@@ -0,0 +1,25 @@
+openapi: 3.0.0
+info:
+  title: Sample API
+  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
+  version: 0.1.9
+servers:
+  - url: 'http://api.example.com/v1'
+    description: Optional server description, e.g. Main (production) server
+
+paths:
+  /users:
+    get:
+      summary: Returns a list of users.
+      description: Optional extended description in CommonMark or HTML.
+      operationId: getUsers
+      parameters: []
+      responses:
+        '200':    # status code
+          description: A JSON array of user names
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string

example/templates/mdx/path.hdb

@@ -0,0 +1,54 @@
+---
+id: {{method.operationId}}
+title: {{method.summary}}
+---
+
+<!-- prettier-ignore-start -->
+{{{{rawBlock}}}}
+
+export const Method = ({children, color}) => (
+  <span
+    style={{
+      backgroundColor: color,
+      borderRadius: '6px',
+      color: '#fff',
+      padding: '0.6rem 1.2rem',
+      textTransform: 'uppercase',
+      fontWeight: 'bold'
+    }}>
+    {children}
+  </span>
+);
+
+export const Path = ({children}) => (
+  <span
+    style={{
+      borderRadius: '6px',
+      color: '#000',
+      paddingLeft: '0.8rem',
+      textTransform: 'lowercase',
+      fontWeight: 'bold',
+      fontsSize: '1.2rem'
+    }}>
+    {children}
+  </span>
+);
+
+export const Url = ({children}) => {
+  return (
+    <div
+      style={{
+        marginBottom: '3rem',
+        paddingTop: '1rem'
+      }}>
+      {children}
+    </div>
+  );
+};
+
+{{{{/rawBlock}}}}
+<!-- prettier-ignore-end -->
+
+<Url>
+  <Method color="#6b55b2">{{httpMethod}}</Method><Path>{unescape(escape('{{path}}'))}</Path>
+</Url>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synx-ai/oas3-mdx",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Convert OpenAPI spec to Markdown files.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -62,6 +62,7 @@
     "husky": "^5.1.1",
     "jest": "^26.6.3",
     "pinst": "^2.1.6",
+    "speccy": "^0.11.0",
     "ts-jest": "^26.5.2",
     "typescript": "^4.1.5"
   },

readme.md

@@ -30,7 +30,7 @@ Options:
       --version   Show version number                         [boolean]
   -s, --spec      OpenAPI specification                      [required]
   -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
 ```
@@ -49,7 +49,7 @@ convert('./example/petstore.json' /*, { outPath: 'my_path' }*/);
 | ------------------ | ------------ | -------------------- | ------------- |
 | `OpenAPI spec`     | --spec       | specFile             | _None_        |
 | `Target build dir` | --target     | outPath              | `./build`     |
-| `Templates dir`    | --templates  | templatePath         | `./templates` |
+| `Templates dir`    | --templates  | templatesPath        | `./templates` |
 | `Snippet targets`  | --snipetts   | snippetTargets       | `["shell"]`   |
 | `Prettier parser`  | --parser     | prettierParser       | `mdx`         |
 

src/cli.ts

@@ -47,7 +47,7 @@ const argv = yargs(hideBin(process.argv))
 // call the convert function from ./index.js
 convert(path.resolve(process.cwd(), argv.spec), {
   outPath: path.resolve(process.cwd(), argv.target),
-  templatePath: path.resolve(argv.templates),
+  templatesPath: path.resolve(argv.templates),
   snippetTargets: argv.snippets.split(","),
   prettierParser: argv.parser,
 })

src/index.ts

@@ -65,7 +65,7 @@ type Optional = {
   outPath?: string;
 
   /** @default "../templates/" */
-  templatePath?: string;
+  templatesPath?: string;
 
   /** @default ["curl"] */
   snippetTargets?: string[];
@@ -78,14 +78,14 @@ type Optional = {
  * Convert openapi spec to markdown
  * @param   {string}    specFile specification file
  * @param   {string}    outPath path to write documents
- * @param   {string}    templatePath path to markdown templates
+ * @param   {string}    templatesPath path to markdown templates
  * @returns {Promise<void>}
  */
 const convert = (specFile: string, options: Optional = {}): Promise<void> => {
   return new Promise((resolve, reject) => {
     const {
       outPath = path.resolve(process.cwd(), "./build"),
-      templatePath = "../templates/",
+      templatesPath = "../templates/",
       snippetTargets = ["shell"],
       prettierParser = "mdx",
     } = options;
@@ -139,13 +139,13 @@ const convert = (specFile: string, options: Optional = {}): Promise<void> => {
 
           let pathTemplate;
 
-          if (fs.existsSync(path.resolve(process.cwd(), templatePath, "path.hdb"))) {
+          if (fs.existsSync(path.resolve(process.cwd(), templatesPath, "path.hdb"))) {
             pathTemplate = Handlebars.compile(
-              fs.readFileSync(path.resolve(process.cwd(), templatePath, "path.hdb"), "utf8")
+              fs.readFileSync(path.resolve(process.cwd(), templatesPath, "path.hdb"), "utf8")
             );
-          } else if (fs.existsSync(path.resolve(__dirname, templatePath, "path.hdb"))) {
+          } else if (fs.existsSync(path.resolve(__dirname, templatesPath, "path.hdb"))) {
             pathTemplate = Handlebars.compile(
-              fs.readFileSync(path.resolve(__dirname, templatePath, "path.hdb"), "utf8")
+              fs.readFileSync(path.resolve(__dirname, templatesPath, "path.hdb"), "utf8")
             );
           } else {
             reject("Can not find templates path");