interagent/prmd là một trong những repo mã nguồn mở mà TopGit theo dõi, hiện có 2.1k sao, viết chủ yếu bằng Ruby. JSON Schema tools and doc generation for HTTP APIs
Tóm tắt dựng từ metadata GitHub của chính dự án — chưa có bài review TopGit. Trang sẽ tự động cập nhật khi bài review đầy đủ được xuất bản.
VÌ SAO CHƯA CÓ REVIEW
TopGit viết bài đầy đủ cho repo có nhiều sao nhất và được yêu cầu nhiều nhất. Trang này là snapshot trong thời gian chờ — xem README gốc ở tab READ ME.
JSON Schema tooling: scaffold, verify, and generate documentation
from JSON Schema documents.
Introduction
JSON Schema provides a great way to describe
an API. prmd provides tools for bootstrapping a description like this,
verifying its completeness, and generating documentation from the
specification.
To learn more about JSON Schema in general, start with
this excellent guide
and supplement with the specification.
The JSON Schema usage conventions expected by prmd specifically are
described in /docs/schemata.md.
Installation
Install the command-line tool with:
$ gem install prmd
If you're using prmd within a Ruby project, you may want to add it
to the application's Gemfile:
gem 'prmd'
$ bundle install
Usage
Prmd provides four main commands:
init: Scaffold resource schemata
combine: Combine schemata and metadata into single schema
verify: Verify a schema
doc: Generate documentation from a schema
render: Render views from schema
Here's an example of using these commands in a typical workflow:
# 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
Using YAML instead of JSON as a resource and meta format
init and combine supports YAML format:
# 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 can detect both *.yml and *.json and use them side by side. For example, if one have a lot of legacy JSON resources and wants to create new resources in YAML format - combine will be able to handle it properly.
{
"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)
}
}
Use as rake task
In addition, prmd can be used via rake tasks
# 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']
File Layout
We suggest the following file layout for JSON schema related files:
/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)
where [json,yml] means that it could be either json or yml.
Contributing
Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Trang TopGit này là một snapshot — tab "Readme" hiển thị nguyên văn README của repo (đã bỏ link, giữ ảnh). Repo GitHub ở github.com/interagent/prmd là nguồn chính thức.
interagent/prmd có bao nhiêu sao?
interagent/prmd có 2.1k sao GitHub — tải lại trang để xem số mới nhất, hoặc xem trực tiếp github.com/interagent/prmd. TopGit phản chiếu số sao của GitHub nhưng không cam kết đến từng phút.
interagent/prmd có phải mã nguồn mở không?
Có — interagent/prmd phát hành theo license MIT, nghĩa là mã nguồn mở để đọc, fork và (tùy license) tái sử dụng. Mã: github.com/interagent/prmd.
interagent/prmd có tag gì không?
Bản đồng bộ chưa ghi nhận topic GitHub nào cho interagent/prmd. GitHub topics hiển thị ở thanh bên phải trang repo — đó là nơi đáng kiểm tra nhất.
interagent/prmd có website riêng không?
TopGit chưa ghi nhận URL trang chủ cho interagent/prmd. Phần README ở tab phía trên thường có link demo, hoặc xem mô tả GitHub của repo.
interagent/prmd còn đang phát triển không?
Commit gần nhất trên interagent/prmd là 1.5 năm trước (theo timestamp GitHub). Repo có 169 fork — một chỉ báo về mức độ quan tâm của cộng đồng.
Đọc đầy đủ README ở tab phía trên.
prmd có đáng để bạn bỏ thời gian?
ChatGPT, Claude và Perplexity đều đọc được trang này. Hỏi thử xem họ nghĩ gì về prmd.
/prmd