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

  • Z时代
  • 2024-01-10
  • 分类：综合

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

以上是 Prmd 验证和生成 来自 JSON Schema 的文档 的全部内容， 来源链接： utcz.com/z/264576.html

回到顶部