Widdershins 项目使用文档

Widdershins 项目使用文档

widdershinsOpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown项目地址:https://gitcode.com/gh_mirrors/wi/widdershins

1. 项目的目录结构及介绍

Widdershins 是一个用于将 OpenAPI 3.x, OpenAPI 2.0 (Swagger), API Blueprint, AsyncAPI 或 Semoasa 格式的 API 定义转换为 Markdown 格式的工具。以下是 Widdershins 项目的主要目录结构及其介绍：

widdershins/
├── bin/
│   └── widdershins.js
├── lib/
│   ├── ...
│   └── index.js
├── templates/
│   ├── ...
│   └── main.dot
├── test/
│   ├── ...
│   └── test.js
├── .gitignore
├── .npmignore
├── .travis.yml
├── LICENSE
├── README.md
├── package.json
└── yarn.lock

• bin/: 包含可执行文件 widdershins.js，用于启动 Widdershins。
• lib/: 包含项目的主要逻辑代码。
• templates/: 包含用于生成文档的模板文件。
• test/: 包含测试文件。
• .gitignore: 指定 Git 版本控制系统忽略的文件和目录。
• .npmignore: 指定 npm 发布时忽略的文件和目录。
• .travis.yml: Travis CI 配置文件。
• LICENSE: 项目许可证。
• README.md: 项目说明文档。
• package.json: 项目依赖和脚本配置。
• yarn.lock: Yarn 包管理器的锁定文件。

2. 项目的启动文件介绍

Widdershins 的启动文件位于 bin/ 目录下，名为 widdershins.js。该文件是 Widdershins 的入口点，负责解析命令行参数并调用 lib/ 目录中的主要逻辑代码来执行转换操作。

以下是 widdershins.js 文件的简要介绍：

#!/usr/bin/env node

const yargs = require('yargs');
const converter = require('../lib/index.js');

const argv = yargs
  .usage('Usage: $0 -i <input file> -o <output file> [options]')
  .demandOption(['i', 'o'])
  .describe('i', 'Input file (OpenAPI or Swagger JSON/YAML)')
  .describe('o', 'Output file (Markdown)')
  .help('h')
  .alias('h', 'help')
  .argv;

converter.convert(argv);

• #!/usr/bin/env node: 指定使用 Node.js 执行该脚本。
• yargs: 用于解析命令行参数。
• converter: 导入 lib/index.js 中的转换逻辑。
• argv: 解析后的命令行参数。
• converter.convert(argv): 调用转换逻辑并传入解析后的参数。

3. 项目的配置文件介绍

Widdershins 的配置主要通过命令行参数进行，但也可以通过 package.json 文件中的 config 字段进行一些默认配置。以下是 package.json 文件中与配置相关的部分：

{
  "name": "widdershins",
  "version": "4.0.1",
  "description": "OpenAPI / Swagger / AsyncAPI / Semoasa definition to Slate / Shins compatible markdown",
  "bin": {
    "widdershins": "bin/widdershins.js"
  },
  "config": {
    "maxDepth": 10
  },
  "scripts": {
    "test": "node test/test.js"
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  }
}

• bin: 指定可执行文件的路径。
• config: 包含默认配置，例如 maxDepth 用于限制 schema 示例的深度。
• scripts: 包含项目脚本，例如 test 用于运行测试。

通过命令行参数，可以覆盖 config 字段中的默认配置。例如：

widdershins -i input.json -o output.md --max

widdershinsOpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown项目地址:https://gitcode.com/gh_mirrors/wi/widdershins