json-schema-docs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd5892af89b1910f3b373a462c2fb4854cf1626b15031f44a7f3d5b6b7280c3d
+  data.tar.gz: 65c3110d0ab1e4397fafca814423daae4bc5bf3c5e34bdb087c9fa346e0615f5
+SHA512:
+  metadata.gz: b9dbb7897d5d73835f56ad12cdbacf9e0aa14ba97a6e7ee04c630ba0158bac274cc03b8216102b2034ba580d49b54352b3bfe7f65a3254c30a6814e5b6eeb94d
+  data.tar.gz: 98ba7a96d3e77c85d4ca35bf7f56254b35ad62cd6162978a3ce2d95bf20c35e3d9a2b17894a7457c1a8d625aa702ff255068eeaedfef5b71b6d601284c97b074

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/output/
+test/json-schema-docs/fixtures/output
+/.sass-cache/
+/output/
+.byebug_history

data/.rubocop.yml

@@ -0,0 +1,10 @@
+inherit_gem:
+  rubocop-standard:
+    - config/default.yml
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Naming/FileName:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,23 @@
+sudo: false
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.3.6
+  - 2.4.3
+  - 2.5.0
+  - 2.6.0
+
+git:
+  depth: 10
+
+before_install:
+  - gem update --system
+  - gem install bundler
+
+matrix:
+  include:
+    - script: bundle exec rake rubocop
+      rvm: 2.6.0
+    - script: bundle exec rake html_proofer
+      rvm: 2.6.0

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in json-schema-docs.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Garen Torikian
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# json-schema-docs
+
+Inspired by [prmd](https://github.com/interagent/prmd)'s doc generation, this is a stand-alone gem to generate Markdown files from a single JSON schema file. `prmd`'s doc generator is rather opinionated, and I did not like its opinions. 😅
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json-schema-docs'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install json-schema-docs
+
+## Usage
+
+``` ruby
+# pass in a filename
+JsonSchemaDocs.build(filename: filename)
+
+# or pass in a string
+JsonSchemaDocs.build(schema: contents)
+
+# or a schema class
+schema = Prmd::Schema.new(data)
+JsonSchemaDocs.build(schema: schema)
+```
+
+
+## Breakdown
+
+There are several phases going on the single `JsonSchemaDocs.build` call:
+
+* The JSON schema file is read (if you passed `filename`) through `Prmd::Schema` (or simply consumed if you passed it through `schema`).
+* `JsonSchemaDocs::Parser` manipulates the schema into a slightly saner format.
+* `JsonSchemaDocs::Generator` takes that saner format and converts it into Markdown, via ERB templates.
+
+If you wanted to, you could break these calls up individually. For example:
+
+``` ruby
+options = {}
+options[:filename] = "#{File.dirname(__FILE__)}/../data/schema.json"
+
+options = JsonSchemaDocs::Configuration::JSON_SCHEMA_DOCS.merge(options)
+
+response = File.read(options[:filename])
+
+parser = JsonSchemaDocs::Parser.new(response, options)
+parsed_schema = parser.parse
+
+generator = JsonSchemaDocs::Generator.new(parsed_schema, options)
+
+generator.generate
+```
+
+## Generating output
+
+By default, the generation process uses ERB to layout the content into Markdown.
+
+### Helper methods
+
+In your ERB layouts, there are several helper methods you can use. The helper methods are:
+
+* `slugify(str)` - This slugifies the given string.
+* `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.
+
+## Configuration
+
+The following options are available:
+
+| Option | Description | Default |
+| :----- | :---------- | :------ |
+| `filename` | The location of your schema's IDL file. | `nil` |
+| `schema` | A string representing a schema IDL file. | `nil` |
+| `delete_output` | Deletes `output_dir` before generating content. | `false` |
+| `output_dir` | The location of the output Markdown files. | `./output/` |
+| `templates` | The templates to use when generating Markdown files. You may override any of the following keys: `endpoint`, `object`, `includes`. | The defaults are found in _lib/json-schema-docs/layouts/_.
+| `prmd` | The options to pass into PRMD's parser. | The defaults are found in _lib/json-schema-docs/configuration.rb/_.
+
+## Development
+
+After checking out the repo, run `script/bootstrap` to install dependencies. Then, run `rake test` to run the tests. You can also run `bundle exec rake console` for an interactive prompt that will allow you to experiment.
+
+## Sample site
+
+Clone this repository and run:
+
+```
+bundle exec rake sample
+```
+
+to see some sample output.

data/Rakefile

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop)
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.warning = false
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test
+
+desc 'Generate the documentation'
+task :generate_sample do
+  require 'pry'
+  require 'json-schema-docs'
+
+  options = {}
+  options[:delete_output] = true
+  options[:filename] = File.join(File.dirname(__FILE__), 'test', 'json-schema-docs', 'fixtures', 'heroku.json')
+
+  JsonSchemaDocs.build(options)
+end
+
+desc 'Generate the documentation and run a web server'
+task sample: [:generate_sample] do
+  require 'webrick'
+
+  puts 'Navigate to http://localhost:3000 to see the sample docs'
+
+  mime_types = WEBrick::HTTPUtils::DefaultMimeTypes
+  mime_types.store 'md', 'text/plain'
+
+  options = {
+    Port: 3000,
+    MimeTypes: mime_types
+  }
+  server = WEBrick::HTTPServer.new options
+  server.mount '/', WEBrick::HTTPServlet::FileHandler, 'output'
+  trap('INT') { server.stop }
+  server.start
+end

data/json-schema-docs.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+# frozen_string_literal: true
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'json-schema-docs/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'json-schema-docs'
+  spec.version       = JsonSchemaDocs::VERSION
+  spec.authors       = ['Garen Torikian']
+  spec.email         = ['gjtorikian@gmail.com']
+
+  spec.summary       = 'Easily generate Markdown files from your JSON schema.'
+  spec.homepage      = 'https://github.com/gjtorikian/json-schema-docs'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'bin'
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'prmd', '~> 0.13'
+
+  spec.add_development_dependency 'awesome_print'
+  spec.add_development_dependency 'html-proofer', '~> 3.4'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'minitest-focus', '~> 1.1'
+  spec.add_development_dependency 'pry-byebug', '~> 3.6'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-standard'
+end

data/lib/json-schema-docs/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module JsonSchemaDocs
+  module Configuration
+    JSON_SCHEMA_DOCS_DEFAULTS = {
+      # initialize
+      filename: nil,
+      schema: nil,
+
+      # Generating
+      delete_output: false,
+      output_dir: './output/',
+
+      templates: {
+        endpoint: "#{File.dirname(__FILE__)}/layouts/endpoint.md.erb",
+        object: "#{File.dirname(__FILE__)}/layouts/object.md.erb",
+
+        includes: "#{File.dirname(__FILE__)}/layouts/includes",
+      },
+
+      prmd: {
+        http_header: {},
+        content_type: 'application/json',
+        doc: {
+          url_style: 'default'
+        }
+      }
+    }.freeze
+  end
+end

data/lib/json-schema-docs/generator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+require 'erb'
+
+module JsonSchemaDocs
+  class Generator
+    include Helpers
+
+    attr_accessor :parsed_schema
+
+    def initialize(parsed_schema, options)
+      @parsed_schema = parsed_schema
+      @options = options
+
+      %i(endpoint object).each do |sym|
+        if !File.exist?(@options[:templates][sym])
+          raise IOError, "`#{sym}` template #{@options[:templates][sym]} was not found"
+        end
+        instance_variable_set("@json_schema_#{sym}_template", ERB.new(File.read(@options[:templates][sym]), nil, '-'))
+      end
+    end
+
+    def generate
+      FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
+
+      @parsed_schema.each_pair do |resource, schemata|
+        %i(endpoint object).each do |type|
+          contents = render(type, schemata)
+          write_file(type, resource, contents)
+
+          contents = render(type, schemata)
+          write_file(type, resource, contents)
+        end
+      end
+    end
+
+    private
+
+    def render(type, schemata)
+      layout = instance_variable_get("@json_schema_#{type}_template")
+      opts = @options.merge(helper_methods)
+
+      opts[:schemata] = schemata
+      layout.result(OpenStruct.new(opts).instance_eval { binding })
+    end
+
+    def write_file(type, name, contents, trim: true)
+      if type == :object
+        path = File.join(@options[:output_dir], 'objects', name.downcase)
+        FileUtils.mkdir_p(path)
+      elsif type == :endpoint
+        path = File.join(@options[:output_dir], 'objects', name.downcase, 'endpoints')
+        FileUtils.mkdir_p(path)
+      end
+
+      if trim
+        # normalize spacing so that CommonMarker doesn't treat it as `pre`
+        contents = contents.gsub(/^\s+$/, '')
+        contents = contents.gsub(/^\s{4}/m, '  ')
+      end
+
+      filename = File.join(path, 'index.md')
+      File.write(filename, contents) unless contents.nil?
+    end
+  end
+end

data/lib/json-schema-docs/helpers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JsonSchemaDocs
+  module Helpers
+    SLUGIFY_PRETTY_REGEXP = Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze
+
+    attr_accessor :templates
+
+    def slugify(str)
+      slug = str.gsub(SLUGIFY_PRETTY_REGEXP, '-')
+      slug.gsub!(%r!^\-|\-$!i, '')
+      slug.downcase
+    end
+
+    def include(filename, opts = {})
+      template = fetch_include(filename)
+      opts = @options.merge(opts)
+      template.result(OpenStruct.new(opts.merge(helper_methods)).instance_eval { binding })
+    end
+
+    private
+
+    def fetch_include(filename)
+      @templates ||= {}
+
+      return @templates[filename] unless @templates[filename].nil?
+
+      contents = File.read(File.join(@options[:templates][:includes], filename))
+
+      @templates[filename] = ERB.new(contents, nil, '-')
+    end
+
+    def helper_methods
+      return @helper_methods if defined?(@helper_methods)
+
+      @helper_methods = {}
+
+      Helpers.instance_methods.each do |name|
+        next if name == :helper_methods
+        @helper_methods[name] = method(name)
+      end
+
+      @helper_methods
+    end
+  end
+end

data/lib/json-schema-docs/layouts/endpoint.md.erb

@@ -0,0 +1,39 @@
+#  <a class="header-link" name="resource-<%= schemata['title'] %>"><%= schemata['title'] %></a>
+
+<% (schemata['links'] || []).each do |link, datum| %>
+
+## <a class="header-link" name="link-<%= link['method'] %>-<%= resource %>-<%= link['href'] %>"><%= schemata['title'] %> <%= link['title'] %></a>
+
+<%= link['description'] %>
+
+```
+<%= link['method'] %> <%= link['link_path'] %>
+```
+
+<% if link['required_properties'] && !link['required_properties'].empty? %>
+## Required Parameters
+
+| Name | Type | Description | Example |
+| ------- | ------- | ------- | ------- |
+<%- link['required_properties'].each do |property_ref| -%>
+| **<%= property_ref[:name] %>** | *<%= property_ref[:type] %>* | <%= property_ref[:description] %> | <%= property_ref[:example] %> |
+<%- end -%>
+
+<% end %>
+
+<% if link['optional_properties'] && !link['optional_properties'].empty? %>
+## Optional Parameters
+
+| Name | Type | Description | Example |
+| ------- | ------- | ------- | ------- |
+<%- link['optional_properties'].each do |property_ref| -%>
+| **<%= property_ref[:name] %>** | *<%= property_ref[:type] %>* | <%= property_ref[:description] %> | <%= property_ref[:example] %> |
+<%- end -%>
+
+<% end %>
+
+<%= include.('example.md.erb', example: link['example']) %>
+
+<%= include.('response.md.erb', response: link['response']) %>
+
+<% end %>

data/lib/json-schema-docs/layouts/includes/example.md.erb

@@ -0,0 +1,11 @@
+## Curl Example
+
+```bash
+$ curl -n <%= example[:request] -%><%- unless example[:http_headers].empty? %> \<%- end -%>
+<%- if !example[:data].nil? %>
+  <%= example[:data] -%>
+<%- end -%>
+<%- example[:http_headers].each do |key, value| %>
+  -H "<%= key %>: <%= value %>"<%- if key != example[:http_headers].keys.last %> \<%- end -%>
+<%- end %>
+```

data/lib/json-schema-docs/layouts/includes/response.md.erb

@@ -0,0 +1,11 @@
+## Response Example
+
+```
+<%= response[:header] %>
+```
+
+<% unless response[:example].nil? %>
+```json
+<%= response[:example] %>
+```
+<% end %>

data/lib/json-schema-docs/layouts/object.md.erb

@@ -0,0 +1,17 @@
+# <a class="header-link" name="resource-<%= schemata['title'].downcase %>"><%= schemata['title'] %></a>
+
+<% if schemata['stability'] && !schemata['stability'].empty? %>
+Stability: `<%= schemata['stability'] %>`
+<% end %>
+
+<%= schemata['description'] %>
+
+<% if schemata['property_refs'] && !schemata['property_refs'].empty? %>
+## Attributes
+
+| Name | Type | Description | Example |
+| ------- | ------- | ------- | ------- |
+<%- schemata['property_refs'].each do |property_ref| -%>
+| **<%= property_ref[:name] %>** | *<%= property_ref[:type] %>* | <%= property_ref[:description] %> | <%= property_ref[:example] %> |
+<%- end -%>
+<% end %>

data/lib/json-schema-docs/parser.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+require 'prmd'
+
+module JsonSchemaDocs
+  class Parser
+    include Helpers
+
+    attr_reader :processed_schema
+
+    def initialize(schema, options)
+      @options = options
+
+      if schema.is_a?(Prmd::Schema)
+        @schema = schema
+      else
+        # FIXME: Multiloader has issues: https://github.com/interagent/prmd/issues/279
+        # for now just always assume a JSON file
+        data = Prmd::MultiLoader::Json.load_data(schema)
+
+        @schema = Prmd::Schema.new(data)
+      end
+
+      @processed_schema = {}
+    end
+
+    def parse
+      @schema['properties'].each_key do |key|
+        resource, property = key, @schema['properties'][key]
+        begin
+          _, schemata = @schema.dereference(property)
+
+          # establish condensed object description
+          if schemata['properties'] && !schemata['properties'].empty?
+            schemata['property_refs'] = []
+            refs = extract_schemata_refs(@schema, schemata['properties']).map { |v| v && v.split('/') }
+            extract_attributes(@schema, schemata['properties']).each_with_index do |(key, type, description, example), i|
+              property_ref = { type: type, description: description, example: example}
+              if refs[i] && refs[i][1] == 'definitions' && refs[i][2] != resource
+                property_ref[:name] = '[%s](#%s)' % [key, 'resource-' + refs[i][2]]
+              else
+                property_ref[:name] = key
+              end
+              schemata['property_refs'].push(property_ref)
+            end
+          end
+
+          # establish full link description
+          (schemata['links'] || []).each do |link, datum|
+            link_path = build_link_path(@schema, link)
+            response_example = link['response_example']
+
+            if link.has_key?('schema') && link['schema'].has_key?('properties')
+              required, optional = Prmd::Link.new(link).required_and_optional_parameters
+
+              unless required.empty?
+                link_schema_required_properties = extract_attributes(@schema, required).map do |(name, type, description, example)|
+                  { name: name, type: type, description: description, example: example}
+                end
+              end
+
+              unless optional.empty?
+                link_schema_optional_properties = extract_attributes(@schema, optional).map do |(name, type, description, example)|
+                  { name: name, type: type, description: description, example: example}
+                end
+              end
+            end
+
+            link['link_path'] = link_path
+            link['required_properties'] = link_schema_required_properties
+            link['optional_properties'] = link_schema_optional_properties
+            link['example'] = generate_example(link, link_path)
+            link['response'] = {
+              header: generate_response_header(response_example, link),
+              example: generate_response_example(response_example, link, resource)
+            }
+          end
+
+          @processed_schema[resource] = schemata
+        rescue => e
+          $stdout.puts("Error in resource: #{resource}")
+          raise e
+        end
+      end
+
+      @processed_schema
+    end
+
+    private
+
+    def extract_attributes(schema, properties)
+      attributes = []
+
+      _, properties = schema.dereference(properties)
+
+      properties.each do |key, value|
+        # found a reference to another element:
+        _, value = schema.dereference(value)
+
+        # include top level reference to nested things, when top level is nullable
+        if value.has_key?('type') && value['type'].include?('null') && (value.has_key?('items') || value.has_key?('properties'))
+          attributes << build_attribute(schema, key, value)
+        end
+
+        if value.has_key?('anyOf')
+          descriptions = []
+          examples = []
+
+          anyof = value['anyOf']
+
+          anyof.each do |ref|
+            _, nested_field = schema.dereference(ref)
+            descriptions << nested_field['description'] if nested_field['description']
+            examples << nested_field['example'] if nested_field['example']
+          end
+
+          # avoid repetition :}
+          description = if descriptions.size > 1
+            descriptions.first.gsub!(/ of (this )?.*/, '')
+            descriptions[1..-1].map { |d| d.gsub!(/unique /, '') }
+            [descriptions[0...-1].join(', '), descriptions.last].join(' or ')
+          else
+            description = descriptions.last
+          end
+
+          example = [*examples].map { |e| "`#{e.to_json}`" }.join(' or ')
+          attributes << [key, 'string', description, example]
+
+        # found a nested object
+        elsif value['properties']
+          nested = extract_attributes(schema, value['properties'])
+          nested.each do |attribute|
+            attribute[0] = "#{key}:#{attribute[0]}"
+          end
+          attributes.concat(nested)
+
+        elsif array_with_nested_objects?(value['items'])
+          if value['items']['properties']
+            nested = extract_attributes(schema, value['items']['properties'])
+            nested.each do |attribute|
+              attribute[0] = "#{key}/#{attribute[0]}"
+            end
+            attributes.concat(nested)
+          end
+          if value['items']['oneOf']
+            value['items']['oneOf'].each_with_index do |oneof, index|
+            ref,  oneof_definition = schema.dereference(oneof)
+            oneof_name = ref ? ref.split('/').last : index
+            nested = extract_attributes(schema, oneof_definition['properties'])
+            nested.each do |attribute|
+              attribute[0] = "#{key}/[#{oneof_name.upcase}].#{attribute[0]}"
+            end
+            attributes.concat(nested)
+            end
+        end
+
+        # just a regular attribute
+        else
+          attributes << build_attribute(schema, key, value)
+        end
+      end
+      attributes.map! { |key, type, description, example|
+        if example.nil? && Prmd::DefaultExamples.key?(type)
+          example = '`%s`' % Prmd::DefaultExamples[type].to_json
+        end
+        [key, type, description, example]
+      }
+      return attributes.sort
+    end
+
+    def extract_schemata_refs(schema, properties)
+      ret = []
+      properties.keys.sort.each do |key|
+        value = properties[key]
+        ref, value = schema.dereference(value)
+        if value['properties']
+          refs = extract_schemata_refs(schema, value['properties'])
+        elsif value['items'] && value['items']['properties']
+          refs = extract_schemata_refs(schema, value['items']['properties'])
+        else
+          refs = [ref]
+        end
+        if value.has_key?('type') && value['type'].include?('null') && (value.has_key?('items') || value.has_key?('properties'))
+          # A nullable object usually isn't a reference to another schema. It's
+          # either not a reference at all, or it's a reference within the same
+          # schema. Instead, the definition of the nullable object might contain
+          # references to specific properties.
+          #
+          # If all properties refer to the same schema, we'll use that as the
+          # reference. This might even overwrite an actual, intra-schema
+          # reference.
+
+          l = refs.map { |v| v && v.split('/')[0..2] }
+          if l.uniq.size == 1 && l[0] != nil
+            ref = l[0].join('/')
+          end
+          ret << ref
+        end
+        ret.concat(refs)
+      end
+      ret
+    end
+
+    def build_attribute(schema, key, value)
+      description = value['description'] || ''
+      if value['default']
+        description += "<br/> **default:** `#{value['default'].to_json}`"
+      end
+
+      if value['minimum'] || value['maximum']
+        description += '<br/> **Range:** `'
+        if value['minimum']
+          comparator = value['exclusiveMinimum'] ? '<' : '<='
+          description += "#{value['minimum'].to_json} #{comparator} "
+        end
+        description += 'value'
+        if value['maximum']
+          comparator = value['exclusiveMaximum'] ? '<' : '<='
+          description += " #{comparator} #{value['maximum'].to_json}"
+        end
+        description += '`'
+      end
+
+      if value['enum']
+        description += '<br/> **one of:**' + [*value['enum']].map { |e| "`#{e.to_json}`" }.join(' or ')
+      end
+
+      if value['pattern']
+        description += "<br/> **pattern:** `#{value['pattern']}`"
+      end
+
+      if value['minLength'] || value['maxLength']
+        description += '<br/> **Length:** `'
+        if value['minLength']
+          description += "#{value['minLength'].to_json}"
+        end
+        unless value['minLength'] == value['maxLength']
+          if value['maxLength']
+            unless value['minLength']
+              description += '0'
+            end
+            description += "..#{value['maxLength'].to_json}"
+          else
+            description += '..∞'
+          end
+        end
+        description += '`'
+      end
+
+      if value.has_key?('example')
+        example = if value['example'].is_a?(Hash) && value['example'].has_key?('oneOf')
+          value['example']['oneOf'].map { |e| "`#{e.to_json}`" }.join(' or ')
+        else
+          "`#{value['example'].to_json}`"
+        end
+      elsif (value['type'] == ['array'] && value.has_key?('items')) || value.has_key?('enum')
+        example = "`#{schema.schema_value_example(value).to_json}`"
+      elsif value['type'].include?('null')
+        example = '`null`'
+      end
+
+      type = if value['type'].include?('null')
+        'nullable '
+      else
+        ''
+      end
+      type += (value['format'] || (value['type'] - ['null']).first)
+      [key, type, description, example]
+    end
+
+
+    def build_link_path(schema, link)
+      link['href'].gsub(%r|(\{\([^\)]+\)\})|) do |ref|
+        ref = ref.gsub('%2F', '/').gsub('%23', '#').gsub(%r|[\{\(\)\}]|, '')
+        ref_resource = ref.split('#/definitions/').last.split('/').first.gsub('-', '_')
+        identity_key, identity_value = schema.dereference(ref)
+        if identity_value.has_key?('anyOf')
+          '{' + ref_resource + '_' + identity_value['anyOf'].map { |r| r['$ref'].split('/').last }.join('_or_') + '}'
+        else
+          '{' + ref_resource + '_' + identity_key.split('/').last + '}'
+        end
+      end
+    end
+
+    def array_with_nested_objects?(items)
+      return unless items
+      items['properties'] || items['oneOf']
+    end
+
+    def generate_example(link, link_path)
+      request = {}
+      data = {}
+      headers = {}
+
+      path = link_path.gsub(/{([^}]*)}/) { |match| '$' + match.gsub(/[{}]/, '').upcase }
+      get_params = []
+
+      if link.has_key?('schema')
+        data = @schema.schema_example(link['schema'])
+        if link['method'].upcase == 'GET' && !data.nil?
+          get_params << Prmd::UrlGenerator.new({schema: @schema, link: link, options: @options[:prmd]}).url_params
+        end
+      end
+
+      data = nil if data.empty? # same thing
+
+      # fetch any headers
+      if link['method'].upcase != 'GET'
+        opts = @options[:prmd].dup
+        headers = { 'Content-Type' => opts[:content_type] }.merge(opts[:http_header])
+      end
+
+      # define initial request call
+      if link['method'].upcase != 'GET'
+        request = "-X #{link['method']} #{@schema.href}#{path}"
+      else
+        request = "#{@schema.href}#{path}"
+      end
+
+      # add data, if present
+      if !data.nil? && link['method'].upcase != 'GET'
+        data = "-d '#{JSON.pretty_generate(data)}' \\"
+      elsif !get_params.empty? && link['method'].upcase == 'GET'
+        data = "-G #{get_params.join(" ss\\\n  -d ")} \\"
+      end
+
+      { request: request, data: data, http_headers: headers }
+    end
+
+    def generate_response_header(response_example, link)
+      return response_example['head'] if response_example
+
+      header = 'HTTP/1.1'
+      code = case link['rel']
+      when 'create'
+        '201 Created'
+      when 'empty'
+        '202 Accepted'
+      else
+        '200 OK'
+      end
+      "#{header} #{code}"
+    end
+
+    def generate_response_example(response_example, link, resource)
+      if response_example || link['rel'] != 'empty'
+        if response_example
+          response_example['body']
+        else
+          if link['rel'] == 'empty'
+          elsif link.has_key?('targetSchema')
+            JSON.pretty_generate(@schema.schema_example(link['targetSchema']))
+          elsif link['rel'] == 'instances'
+            JSON.pretty_generate([@schema.schemata_example(resource)])
+          else
+            JSON.pretty_generate(@schema.schemata_example(resource))
+          end
+        end
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/json-schema-docs/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module JsonSchemaDocs
+  VERSION = '0.1.0'.freeze
+end

data/lib/json-schema-docs.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+require 'json-schema-docs/helpers'
+require 'json-schema-docs/configuration'
+require 'json-schema-docs/generator'
+require 'json-schema-docs/parser'
+require 'json-schema-docs/version'
+
+begin
+  require 'awesome_print'
+  require 'pry'
+rescue LoadError; end
+
+module JsonSchemaDocs
+  class << self
+    def build(options)
+      options = JsonSchemaDocs::Configuration::JSON_SCHEMA_DOCS_DEFAULTS.merge(options)
+
+      filename = options[:filename]
+      schema = options[:schema]
+
+      if !filename.nil? && !schema.nil?
+        raise ArgumentError, 'Pass in `filename` or `schema`, but not both!'
+      end
+
+      if filename.nil? && schema.nil?
+        raise ArgumentError, 'Pass in either `filename` or `schema`'
+      end
+
+      if filename
+        unless filename.is_a?(String)
+          raise TypeError, "Expected `String`, got `#{filename.class}`"
+        end
+
+        unless File.exist?(filename)
+          raise ArgumentError, "#{filename} does not exist!"
+        end
+
+        schema = File.read(filename)
+      else
+        if !schema.is_a?(String) && !schema.is_a?(Prmd::Schema)
+          raise TypeError, "Expected `String` or `Prmd::Schema`, got `#{schema.class}`"
+        end
+
+        schema = schema
+      end
+
+      parser = JsonSchemaDocs::Parser.new(schema, options)
+      parsed_schema = parser.parse
+
+      generator = JsonSchemaDocs::Generator.new(parsed_schema, options)
+
+      generator.generate
+    end
+  end
+end

data/script/bootstrap

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+set -e
+
+bundle install "$@"

data/script/console

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+set -e
+
+dir=`pwd`
+
+echo "===> Bundling..."
+script/bootstrap --quiet
+
+echo "===> Launching..."
+bundle exec rake console

metadata

@@ -0,0 +1,203 @@
+--- !ruby/object:Gem::Specification
+name: json-schema-docs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Garen Torikian
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-09-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prmd
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: html-proofer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- gjtorikian@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- json-schema-docs.gemspec
+- lib/json-schema-docs.rb
+- lib/json-schema-docs/configuration.rb
+- lib/json-schema-docs/generator.rb
+- lib/json-schema-docs/helpers.rb
+- lib/json-schema-docs/layouts/endpoint.md.erb
+- lib/json-schema-docs/layouts/includes/example.md.erb
+- lib/json-schema-docs/layouts/includes/response.md.erb
+- lib/json-schema-docs/layouts/object.md.erb
+- lib/json-schema-docs/parser.rb
+- lib/json-schema-docs/version.rb
+- script/bootstrap
+- script/console
+homepage: https://github.com/gjtorikian/json-schema-docs
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: Easily generate Markdown files from your JSON schema.
+test_files: []