- Notifications
You must be signed in to change notification settings - Fork170
JSON Schema tools and doc generation for HTTP APIs
License
interagent/prmd
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
JSON Schema tooling: scaffold, verify, and generate documentationfrom JSON Schema documents.
JSON Schema provides a great way to describean API. prmd provides tools for bootstrapping a description like this,verifying its completeness, and generating documentation from thespecification.
To learn more about JSON Schema in general, start withthis excellent guideand supplement with thespecification.The JSON Schema usage conventions expected by prmd specifically aredescribed in/docs/schemata.md.
Install the command-line tool with:
$ gem install prmd
If you're using prmd within a Ruby project, you may want to add itto the application's Gemfile:
gem'prmd'
$ bundle install
Prmd provides four main commands:
init: Scaffold resource schematacombine: Combine schemata and metadata into single schemaverify: Verify a schemadoc: Generate documentation from a schemarender: 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
init andcombine 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.
$ prmd render --template schemata.erb schema.json> schema.mdTypically you'll want to prepend header and overview information toyour API documentation. You can do this with the--prepend flag:
$ prmd doc --prepend overview.md schema.json> schema.mdYou can also chain commands together as needed, e.g.:
$ prmd combine --meta meta.json schemata/| prmd verify| prmd doc --prepend overview.md> schema.md
Seeprmd <command> --help for additional usage details.
Out of the box you can supply a settings file (in eitherJSON orYAML) that will tweak the layout of your documentation.
$ prmd doc --settings config.json schema.json> schema.mdAvailable options (and their defaults)
{"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)}}
In addition, prmd can be used via rake tasks
# Rakefilerequire'prmd/rake_tasks/combine'require'prmd/rake_tasks/verify'require'prmd/rake_tasks/doc'namespace:schemadoPrmd::RakeTasks::Combine.newdo |t|t.options[:meta]='schema/meta.json'# use meta.yml if you prefer YAML formatt.paths <<'schema/schemata/api't.output_file='schema/api.json'endPrmd::RakeTasks::Verify.newdo |t|t.files <<'schema/api.json'endPrmd::RakeTasks::Doc.newdo |t|t.files={'schema/api.json'=>'schema/api.md'}endendtaskdefault:['schema:combine','schema:verify','schema:doc']
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 eitherjson oryml.
- 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) - Create new Pull Request
About
JSON Schema tools and doc generation for HTTP APIs