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
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>
"name": <string>
}, ..]
Add a new user
POST /user
⇨ Request Body
{
"name": <string>
}
⇦ Response
{
"id": <integer>
"name": <string>
}
Get user by id
GET /user/{id}
↣ Parameter
id
in path
user id (required)
⇦ Response
{
"id": <integer>
"name": <string>
}