oa3-md

1.0.6 • Public • Published

Openapi 3 to Markdown Report

wcs badgenpm version

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

Example Output


User API Spec

Version 1.0.0


This is a oa3-md test specification

Path Table

Method Path Description
GET /user Get user list
POST /user Add a new user
GET /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
}

Package Sidebar

Install

npm i oa3-md

Weekly Downloads

6

Version

1.0.6

License

MIT

Unpacked Size

28.7 kB

Total Files

10

Last publish

Collaborators

  • willicommer