{"id":13654479,"url":"https://github.com/interagent/prmd","last_synced_at":"2025-05-14T04:07:33.252Z","repository":{"id":12646951,"uuid":"15318526","full_name":"interagent/prmd","owner":"interagent","description":"JSON Schema tools and doc generation for HTTP APIs","archived":false,"fork":false,"pushed_at":"2025-02-06T16:33:27.000Z","size":536,"stargazers_count":2095,"open_issues_count":77,"forks_count":170,"subscribers_count":54,"default_branch":"main","last_synced_at":"2025-05-08T03:17:01.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interagent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-19T17:45:58.000Z","updated_at":"2025-04-16T19:11:38.000Z","dependencies_parsed_at":"2024-01-03T05:44:16.357Z","dependency_job_id":"3a09ad9e-0a5f-4ae3-811e-463d936021f5","html_url":"https://github.com/interagent/prmd","commit_stats":null,"previous_names":["heroku/prmd"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fprmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fprmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fprmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fprmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interagent","download_url":"https://codeload.github.com/interagent/prmd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254069215,"owners_count":22009510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T03:00:34.433Z","updated_at":"2025-05-14T04:07:33.207Z","avatar_url":"https://github.com/interagent.png","language":"Ruby","readme":"# Prmd\n\n[![Gem Version](https://badge.fury.io/rb/prmd.svg)](http://badge.fury.io/rb/prmd)\n\nJSON Schema tooling: scaffold, verify, and generate documentation\nfrom JSON Schema documents.\n\n\n## Introduction\n\n[JSON Schema](http://json-schema.org/) provides a great way to describe\nan API. prmd provides tools for bootstrapping a description like this,\nverifying its completeness, and generating documentation from the\nspecification.\n\nTo learn more about JSON Schema in general, start with\n[this excellent guide](http://spacetelescope.github.io/understanding-json-schema/)\nand supplement with the [specification](http://json-schema.org/documentation.html).\nThe JSON Schema usage conventions expected by prmd specifically are\ndescribed in [/docs/schemata.md](/docs/schemata.md).\n\n## Installation\n\nInstall the command-line tool with:\n\n```bash\n$ gem install prmd\n```\n\nIf you're using prmd within a Ruby project, you may want to add it\nto the application's Gemfile:\n\n```ruby\ngem 'prmd'\n```\n\n```bash\n$ bundle install\n```\n\n## Usage\n\nPrmd provides four main commands:\n\n* `init`: Scaffold resource schemata\n* `combine`: Combine schemata and metadata into single schema\n* `verify`: Verify a schema\n* `doc`: Generate documentation from a schema\n* `render`: Render views from schema\n\nHere's an example of using these commands in a typical workflow:\n\n```bash\n# Fill out the resource schemata\n$ mkdir -p schemata\n$ prmd init app  \u003e schemata/app.json\n$ prmd init user \u003e schemata/user.json\n$ vim schemata/{app,user}.json   # edit scaffolded files\n\n# Provide top-level metadata\n$ cat \u003c\u003cEOF \u003e meta.json\n{\n \"description\": \"Hello world prmd API\",\n \"id\": \"hello-prmd\",\n \"links\": [{\n   \"href\": \"https://api.hello.com\",\n   \"rel\": \"self\"\n }],\n \"title\": \"Hello Prmd\"\n}\nEOF\n\n# Combine into a single schema\n$ prmd combine --meta meta.json schemata/ \u003e schema.json\n\n# Check it’s all good\n$ prmd verify schema.json\n\n# Build docs\n$ prmd doc schema.json \u003e schema.md\n```\n\n### Using YAML instead of JSON as a resource and meta format\n\n`init` and `combine` supports YAML format:\n\n```bash\n# Generate resources in YAML format\n$ prmd init --yaml app  \u003e schemata/app.yml\n$ prmd init --yaml user \u003e schemata/user.yml\n\n# Combine into a single schema\n$ prmd combine --meta meta.json schemata/ \u003e schema.json\n```\n\n`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.\n\n# Render from schema\n\n```bash\n$ prmd render --template schemata.erb schema.json \u003e schema.md\n```\n\nTypically you'll want to prepend header and overview information to\nyour API documentation. You can do this with the `--prepend` flag:\n\n```bash\n$ prmd doc --prepend overview.md schema.json \u003e schema.md\n```\n\nYou can also chain commands together as needed, e.g.:\n\n```bash\n$ prmd combine --meta meta.json schemata/ | prmd verify | prmd doc --prepend overview.md \u003e schema.md\n```\n\nSee `prmd \u003ccommand\u003e --help` for additional usage details.\n\n## Documentation rendering settings\n\nOut of the box you can supply a settings file (in either `JSON` or `YAML`) that will tweak the layout of your documentation.\n\n```bash\n$ prmd doc --settings config.json schema.json \u003e schema.md\n```\n\nAvailable options (and their defaults)\n```js\n{\n  \"doc\": {\n    \"url_style\": \"default\", // can also be \"json\"\n    \"disable_title_and_description\": false, // remove the title and the description, useful when using your own custom header\n    \"toc\": false // insert the table of content for json scheme documentation to the top of the file. (default disable)\n  }\n}\n```\n\n## Use as rake task\n\nIn addition, prmd can be used via rake tasks\n\n```ruby\n# Rakefile\nrequire 'prmd/rake_tasks/combine'\nrequire 'prmd/rake_tasks/verify'\nrequire 'prmd/rake_tasks/doc'\n\nnamespace :schema do\n  Prmd::RakeTasks::Combine.new do |t|\n    t.options[:meta] = 'schema/meta.json'    # use meta.yml if you prefer YAML format\n    t.paths \u003c\u003c 'schema/schemata/api'\n    t.output_file = 'schema/api.json'\n  end\n\n  Prmd::RakeTasks::Verify.new do |t|\n    t.files \u003c\u003c 'schema/api.json'\n  end\n\n  Prmd::RakeTasks::Doc.new do |t|\n    t.files = { 'schema/api.json' =\u003e 'schema/api.md' }\n  end\nend\n\ntask default: ['schema:combine', 'schema:verify', 'schema:doc']\n```\n\n## File Layout\n\nWe suggest the following file layout for JSON schema related files:\n\n```\n/docs (top-level directory for project documentation)\n  /schema (API schema documentation)\n    /schemata\n      /{resource.[json,yml]} (individual resource schema)\n    /meta.[json,yml] (overall API metadata)\n    /overview.md (preamble for generated API docs)\n    /schema.json (complete generated JSON schema file)\n    /schema.md (complete generated API documentation file)\n```\n\nwhere `[json,yml]` means that it could be either `json` or `yml`.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","funding_links":[],"categories":["API Documentation","Misc","API representation Languages","Ruby","JSON Schema Tools"],"sub_categories":[".NET",".Dart"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteragent%2Fprmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finteragent%2Fprmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteragent%2Fprmd/lists"}