oa3-md

Openapi 3 to Markdown Report

Converts Openapi 3 specification from YAML- or JSON-file into a compact and easy to read Markdown Report.

Features

• Command line with single parameter
• Consumes Swagger 2 and Openapi 3
• Consumes YAML and JSON
• Compact Markdown output in cheat sheet format
• Configurable

Usage

npm install oa3-md -g

oamd apispec.yaml apispec.md

First parameter is open api spec file name. Default extension is .json if omitted. Second parameter is the output file name. It is the source file name if omitted.

API

const oamd      = require('oa3-md');
const fileIn    = 'user.json';
const fileOut   = 'user.md';
const options   = {
    "advertising": false
}
oamd.oaFileToMdFile( fileIn, fileOut, options );

The package exports:

function oaFileToMdString (oaFile, options = {})

Read file oaFile and return markdown as string.

function oaFileToMdFile (oaFile, mdFile, options = {})

Read file oaFile and write output to file mdFile.

options

Options is content of file config.json

{
    "use_example":              false,
    "default_ext_in":           ".json",
    "default_ext_out":          ".md",
    "advertising":              true,
    "logo":                     true,
    "txt": {
        "pathTable":            "## Path Table",
        "thMethod":             "Method",
        "thPath":               "Path",
        "thDesc":               "Description",
        "pathDetails":          "## Path Details",
        "requestBody":          "##### ⇨ Request Body",
        "requestParams":        "##### ↣ Parameter",
        "response":             "##### ⇦ Response"
    }
}

References

• Recommended Markdown viewer is Typora
• ApiBldr online API Builder
• SwaggerEditor online Swagger Editor

Example Output

---

User API Spec

Version 1.0.0

---

This is a oa3-md test specification

Path Table

| Method | Path | Description | | --- | --- | --- | --- | | [GET](# Get user list) | /user | Get user list | | [POST](# Add a new user) | /user | Add a new user | | [GET](# Get user by id) | /user/{id} | Get user by id |

Path Details

Get user list

GET /user

⇦ Response

[{
    "id": <integer>  // user id
    "name": <string>  // user name
}, ..]

Add a new user

POST /user

⇨ Request Body

{
  "name": <string>  // user name
}

⇦ Response

{
  "id": <integer>  // user id
  "name": <string>  // user name
}

Get user by id

GET /user/{id}

↣ Parameter

• id in path
  user id (required)

⇦ Response

{
  "id": <integer>  // user id
  "name": <string>  // user name
}