Prmd 验证和生成 来自 JSON Schema 的文档

Question

JSON Schema 工具：脚手架、验证和生成文档 来自 JSON Schema 文档。

介绍

JSON Schema 提供了一种很好的描述方式 一个 API。 prmd 提供了用于引导这样的描述的工具， 验证其完整性，并从 规格。

要了解有关 JSON Schema 的更多信息，请从 这个优秀的指南 并补充 规范 。 prmd 特别期望的 JSON Schema 使用约定是 中描述 /docs/schemata.md 。

安装

使用以下命令安装命令行工具：

$ gem install prmd

如果您在 Ruby 项目中使用 prmd，您可能需要添加它 到应用程序的 Gemfile：

gem 'prmd'

$ bundle install

用法

Prmd 提供了四个主要命令：

• init: 脚手架资源模式
• combine: 将模式和元数据组合成一个模式
• verify: 验证架构
• doc: 从模式生成文档
• render: 从模式渲染视图

以下是在典型工作流程中使用这些命令的示例：

# Fill out the resource schemata
$ mkdir -p schemata
$ prmd init app  > schemata/app.json
$ prmd init user > schemata/user.json
$ vim schemata/{app,user}.json   # edit scaffolded files

# Provide top-level metadata
$ cat <<EOF > meta.json
{
 "description": "Hello world prmd API",
 "id": "hello-prmd",
 "links": [{
   "href": "https://api.hello.com",
   "rel": "self"
 }],
 "title": "Hello Prmd"
}
EOF

# Combine into a single schema
$ prmd combine --meta meta.json schemata/ > schema.json

# Check it’s all good
$ prmd verify schema.json

# Build docs
$ prmd doc schema.json > schema.md

使用 YAML 而不是 JSON 作为资源和元格式

init 和 combine 支持 YAML 格式：

# Generate resources in YAML format
$ prmd init --yaml app  > schemata/app.yml
$ prmd init --yaml user > schemata/user.yml

# Combine into a single schema
$ prmd combine --meta meta.json schemata/ > schema.json

combine 可以同时检测到 *.yml 和 *.json 并排使用它们。 例如，如果一个人有很多遗留的 JSON 资源并且想要以 YAML 格式创建新资源 - combine 将能够妥善处理。

从架构渲染

$ prmd render --template schemata.erb schema.json > schema.md

通常，您需要将标题和概述信息添加到 您的 API 文档。 您可以使用 --prepend 选项：

$ prmd doc --prepend overview.md schema.json > schema.md

您还可以根据需要将命令链接在一起，例如：

$ prmd combine --meta meta.json schemata/ | prmd verify | prmd doc --prepend overview.md > schema.md

prmd <command> --help 了解更多使用详情。

文档渲染设置

开箱即用，您可以提供一个设置文件（在任一 JSON 或者 YAML）这将调整您的文档的布局。

$ prmd doc --settings config.json schema.json > schema.md

可用选项（及其默认值）

{
  "doc": {
    "url_style": "default", // can also be "json"
    "disable_title_and_description": false,
    // remove the title and the description, useful when using your own custom header
    "toc": false
    // insert the table of content for json scheme 
    // documentation to the top of the file. (default disable)
  }
}

用作 rake 任务

此外，prmd 可以通过 rake 任务使用

# Rakefile
require 'prmd/rake_tasks/combine'
require 'prmd/rake_tasks/verify'
require 'prmd/rake_tasks/doc'

namespace :schema do
  Prmd::RakeTasks::Combine.new do |t|
    t.options[:meta] = 'schema/meta.json'    # use meta.yml if you prefer YAML format
    t.paths << 'schema/schemata/api'
    t.output_file = 'schema/api.json'
  end

  Prmd::RakeTasks::Verify.new do |t|
    t.files << 'schema/api.json'
  end

  Prmd::RakeTasks::Doc.new do |t|
    t.files = { 'schema/api.json' => 'schema/api.md' }
  end
end

task default: ['schema:combine', 'schema:verify', 'schema:doc']

文件布局

我们建议 JSON 模式相关文件采用以下文件布局：

/docs (top-level directory for project documentation)
  /schema (API schema documentation)
    /schemata
      /{resource.[json,yml]} (individual resource schema)
    /meta.[json,yml] (overall API metadata)
    /overview.md (preamble for generated API docs)
    /schema.json (complete generated JSON schema file)
    /schema.md (complete generated API documentation file)

在哪里 [json,yml] 意味着它可能是 json 或者 yml。

项目地址：https://github.com/interagent/prmd