prmd 0.6.2 → 0.7.0

data/lib/prmd/template.rb

@@ -1,19 +1,76 @@
+require 'erubis'
+require 'json'
+
+# :nodoc:
 module Prmd
+  # Template management
+  #
+  # @api private
   class Template
+    @cache = {}
+
+    # @return [String] location of the prmd templates directory
+    def self.template_dirname
+      File.join(File.dirname(__FILE__), 'templates')
+    end
+
+    # @param [String] args
+    # @return [String] path in prmd's template directory
+    def self.template_path(*args)
+      File.expand_path(File.join(*args), template_dirname)
+    end
+
+    # Clear internal template cache
+    #
+    # @return [void]
+    def self.clear_cache
+      @cache.clear
+    end
+
+    # Attempts to load a template from the given path and base, if the template
+    # was previously loaded, the cached template is returned instead
+    #
+    # @param [String] path
+    # @param [String] base
+    # @return [Erubis::Eruby] eruby template
     def self.load(path, base)
-      fallback = File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+      @cache[[path, base]] ||= begin
+        fallback = template_path
+
+        resolved = File.join(base, path)
+        unless File.exist?(resolved)
+          resolved = File.join(fallback, path)
+        end
 
-      resolved = File.join(base, path)
-      if not File.exist?(resolved)
-        resolved = File.join(fallback, path)
+        Erubis::Eruby.new(File.read(resolved), filename: resolved)
       end
+    end
+
+    #
+    # @param [String] path
+    # @param [String] base
+    # @return (see .load)
+    def self.load_template(path, base)
+      load(path, base)
+    end
 
-      return File.read(resolved)
+    # Render a template given args or block.
+    # args and block are passed to the template
+    #
+    # @param [String] path
+    # @param [String] base
+    # @return [String] result from template render
+    def self.render(path, base, *args, &block)
+      load_template(path, base).result(*args, &block)
     end
 
-    def self.render(path, base, *args)
-      template = self.load(path, base)
-      Erubis::Eruby.new(template).result(*args)
+    # Load a JSON file from prmd's templates directory.
+    # These files are not cached and are intended to be loaded on demand.
+    #
+    # @param [String] filename
+    # @return [Object] data
+    def self.load_json(filename)
+      JSON.parse(File.read(template_path(filename)))
     end
   end
 end

data/lib/prmd/templates/combine_head.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-04/hyper-schema",
+  "definitions": {},
+  "properties": {},
+  "type": ["object"]
+}

data/lib/prmd/templates/init_default.json

@@ -0,0 +1,9 @@
+ {
+  "$schema": "http://json-schema.org/draft-04/hyper-schema",
+  "title": "FIXME",
+  "definitions": {},
+  "description": "FIXME",
+  "links": [],
+  "properties": {},
+  "type": ["object"]
+}

data/lib/prmd/templates/init_resource.json.erb

@@ -0,0 +1,90 @@
+{
+  "id": "schemata/<%= resource %>",
+  "title": "FIXME - <%= resource.capitalize %>",
+  "definitions": {
+    "id": {
+      "description": "unique identifier of <%= resource %>",
+      "example": "01234567-89ab-cdef-0123-456789abcdef",
+      "format": "uuid",
+      "type": ["string"]
+    },
+    "identity": {
+      "$ref": "/schemata/<%= resource %>#/definitions/id"
+    },
+    "created_at": {
+      "description": "when <%= resource %> was created",
+      "example": "2012-01-01T12:00:00Z",
+      "format": "date-time",
+      "type": ["string"]
+    },
+    "updated_at": {
+      "description": "when <%= resource %> was updated",
+      "example": "2012-01-01T12:00:00Z",
+      "format": "date-time",
+      "type": ["string"]
+    }
+  },
+  "properties": {
+    "created_at": {
+      "$ref": "/schemata/<%= resource %>#/definitions/created_at"
+    },
+    "id": {
+      "$ref": "/schemata/<%= resource %>#/definitions/id"
+    },
+    "updated_at": {
+      "$ref": "/schemata/<%= resource %>#/definitions/updated_at"
+    }
+  },
+  "links": [
+    {
+      "description": "Create a new <%= resource %>.",
+      "href": "/<%= resource %>s",
+      "method": "POST",
+      "rel": "create",
+      "schema": {
+        "properties": {},
+        "type": ["object"]
+      },
+      "title": "Create"
+    },
+    {
+      "description": "Delete an existing <%= resource %>.",
+      "href": "/<%= resource %>s/{(%2Fschemata%2F<%= resource %>%23%2Fdefinitions%2Fidentity)}",
+      "method": "DELETE",
+      "rel": "destroy",
+      "title": "Delete"
+    },
+    {
+      "description": "Info for existing <%= resource %>.",
+      "href": "/<%= resource %>s/{(%2Fschemata%2F<%= resource %>%23%2Fdefinitions%2Fidentity)}",
+      "method": "GET",
+      "rel": "self",
+      "title": "Info"
+    },
+    {
+      "description": "List existing <%= resource %>s.",
+      "href": "/<%= resource %>s",
+      "method": "GET",
+      "rel": "instances",
+      "title": "List"
+    },
+    {
+      "description": "Update an existing <%= resource %>.",
+      "href": "/<%= resource %>s/{(%2Fschemata%2F<%= resource %>%23%2Fdefinitions%2Fidentity)}",
+      "method": "PATCH",
+      "rel": "update",
+      "schema": {
+        "properties": {},
+        "type": ["object"]
+      },
+      "title": "Update"
+    }<% if parent %>,
+    {
+      "description": "List existing <%= resource %>s for existing <%= parent %>.",
+      "href": "/<%= parent %>s/{(%2Fschemata%2F<%= parent %>%23%2Fdefinitions%2Fidentity)}/<%= resource %>s",
+      "method": "GET",
+      "rel": "instances",
+      "title": "List"
+    }<% end %>
+  ]
+}

data/lib/prmd/templates/link_schema_properties.md.erb

@@ -0,0 +1,5 @@
+| Name | Type | Description | Example |
+| ------- | ------- | ------- | ------- |
+<%- extract_attributes(schema, params).each do |(key, type, description, example)| %>
+| **<%= key %>** | *<%= type %>* | <%= description %> | <%= example %> |
+<%- end %>

data/lib/prmd/templates/schema.erb

@@ -1,10 +1,10 @@
 <%=
-  schemata_template = Prmd::Template::load('schemata.erb', options[:template])
+  schemata_template = Prmd::Template::load('schemata.md.erb', options[:template])
 
   schema['properties'].map do |resource, property|
     begin
       _, schemata = schema.dereference(property)
-      Erubis::Eruby.new(schemata_template).result({
+      schemata_template.result({
         options:         options,
         resource:        resource,
         schema:          schema,

data/lib/prmd/templates/schemata.md.erb

@@ -0,0 +1,37 @@
+<%-
+  return unless schemata.has_key?('links') && !schemata['links'].empty?
+
+  Prmd::Template.render('schemata/helper.erb', options[:template], {
+    options:         options,
+    resource:        resource,
+    schema:          schema,
+    schemata:        schemata
+  })
+
+  title = schemata['title'].split(' - ', 2).last
+-%>
+<%- unless options[:doc][:disable_title_and_description] %>
+## <%= title %>
+<%= schemata['description'] %>
+<%- end -%>
+
+<%- if schemata['properties'] && !schemata['properties'].empty? %>
+### Attributes
+| Name | Type | Description | Example |
+| ------- | ------- | ------- | ------- |
+<%- extract_attributes(schema, schemata['properties']).each do |(key, type, description, example)| %>
+| **<%= key %>** | *<%= type %>* | <%= description %> | <%= example %> |
+<%- end %>
+<%- end %>
+<%- schemata['links'].each do |link, datum| %>
+<%=
+  Prmd::Template.render('schemata/link.md.erb', options[:template], {
+    options:         options,
+    resource:        resource,
+    schema:          schema,
+    schemata:        schemata,
+    link:            link,
+    title:           title
+  })
+%>
+<%- end -%>

data/lib/prmd/templates/schemata/helper.erb

@@ -1,7 +1,6 @@
 <%-
   def extract_attributes(schema, properties)
     attributes = []
-    properties = properties.sort_by {|k,v| k} # ensure consistent ordering
 
     properties.each do |key, value|
       # found a reference to another element:
@@ -16,15 +15,12 @@
         descriptions = []
         examples = []
 
-        # sort anyOf! always show unique identifier first
-        anyof = value['anyOf'].sort_by do |property|
-          property['$ref'].split('/').last.gsub('id', 'a')
-        end
+        anyof = value['anyOf']
 
         anyof.each do |ref|
           _, nested_field = schema.dereference(ref)
-          descriptions << nested_field['description']
-          examples << nested_field['example']
+          descriptions << nested_field['description'] if nested_field['description']
+          examples << nested_field['example'] if nested_field['example']
         end
 
         # avoid repetition :}
@@ -36,7 +32,7 @@
           description = descriptions.last
         end
 
-        example = [*examples].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
+        example = [*examples].map { |e| "`#{e.to_json}`" }.join(" or ")
         attributes << [key, "string", description, example]
 
       # found a nested object
@@ -62,25 +58,43 @@
   end
 
   def build_attribute(schema, key, value)
-    description = value['description']
+    description = value['description'] || ""
     if value['default']
-      description += "<br/><b>default:</b> <code>#{value['default'].to_json}</code>"
+      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/><b>one of:</b>' + [*value['enum']].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
+      description += '<br/> **one of:**' + [*value['enum']].map { |e| "`#{e.to_json}`" }.join(" or ")
+    end
+
+    if value['pattern']
+      description += "<br/> **pattern:** <code>#{value['pattern'].gsub /\|/, '&#124;'}</code>"
     end
 
     if value.has_key?('example')
       example = if value['example'].is_a?(Hash) && value['example'].has_key?('oneOf')
-        value['example']['oneOf'].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
+        value['example']['oneOf'].map { |e| "`#{e.to_json}`" }.join(" or ")
       else
-        "<code>#{value['example'].to_json}</code>"
+        "`#{value['example'].to_json}`"
       end
     elsif value['type'] == ['array'] && value.has_key?('items')
-      example = "<code>#{schema.schema_value_example(value)}</code>"
+      example = "`#{schema.schema_value_example(value)}`"
     elsif value['type'].include?('null')
-      example = "<code>null</code>"
+      example = "`null`"
     end
 
     type = if value['type'].include?('null')

data/lib/prmd/templates/schemata/link.md.erb

@@ -0,0 +1,74 @@
+<%-
+  path = build_link_path(schema, link)
+  response_example = link['response_example']
+  link_schema_properties_template = Prmd::Template.load_template('link_schema_properties.md.erb', options[:template])
+-%>
+### <%= title %> <%= link['title'] %>
+<%= link['description'] %>
+
+```
+<%= link['method'] %> <%= path %>
+```
+
+<%- if link.has_key?('schema') && link['schema'].has_key?('properties') %>
+  <%-
+    required, optional = link['schema']['properties'].partition do |k, v|
+      (link['schema']['required'] || []).include?(k)
+    end.map { |partition| Hash[partition] }
+  %>
+  <%- unless required.empty? %>
+#### Required Parameters
+<%= link_schema_properties_template.result(params: required, schema: schema, options: options) %>
+
+  <%- end %>
+  <%- unless optional.empty? %>
+#### Optional Parameters
+<%= link_schema_properties_template.result(params: optional, schema: schema, options: options) %>
+  <%- end %>
+<%- end %>
+
+#### Curl Example
+<%=
+  curl_options = options.dup
+  http_header = link['http_header'] || {}
+  curl_options[:http_header] = curl_options[:http_header].merge(http_header)
+  Prmd::Template.render('schemata/link_curl_example.md.erb', File.dirname(options[:template]), {
+    options:         curl_options,
+    resource:        resource,
+    schema:          schema,
+    schemata:        schemata,
+    link:            link,
+    path:            path
+  })
+%>
+
+#### Response Example
+```
+<%- if response_example %>
+<%=   response_example['head'] %>
+<%- else %>
+HTTP/1.1 <%=
+  case link['rel']
+  when 'create'
+    '201 Created'
+  when 'empty'
+    '202 Accepted'
+  else
+    '200 OK'
+  end %>
+<%- end %>
+```
+```json
+<%- 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 %>
+```

data/lib/prmd/templates/schemata/{link_curl_example.erb → link_curl_example.md.erb}

@@ -11,10 +11,16 @@
         get_params << Prmd::UrlGenerator.new({schema: schema, link: link, options: options}).url_params
       end
     end
+    if link['method'].upcase != 'GET'
+      options = options.dup
+      options[:http_header] = { 'Content-Type' => options[:content_type] }.merge(options[:http_header])
+    end
   %>
-$ curl -n -X <%= link['method'] %> <%= schema.href %><%= path -%>
+$ curl -n -X <%= link['method'] %> <%= schema.href %><%= path -%><%- unless options[:http_header].empty? %> \<%- end %>
+  <%- options[:http_header].each do |key, value| %>
+  -H "<%= key %>: <%= value %>" \
+  <%- end %>
 <%- if !data.empty? && link['method'].upcase != 'GET' %> \
-  -H "Content-Type: <%= options[:content_type] %>" \
   -d '<%= JSON.pretty_generate(data) %>'
 <%- elsif !get_params.empty? && link['method'].upcase == 'GET' %> -G \
   -d <%= get_params.join(" \\\n  -d ") %>

data/lib/prmd/url_generator.rb

@@ -1,85 +1,27 @@
+require 'prmd/url_generators/generators/default'
+require 'prmd/url_generators/generators/json'
+
+# :nodoc:
 module Prmd
+  # Schema URL Generation
+  # @api private
   class UrlGenerator
-
+    # @param [Hash<Symbol, Object>] params
     def initialize(params)
       @schema = params[:schema]
       @link = params[:link]
-      @options = params[:options]
+      @options = params.fetch(:options)
     end
 
+    # @return [Array]
     def url_params
-      if @options[:style].downcase == 'json'
+      if @options[:doc][:url_style].downcase == 'json'
         klass = Generators::JSON
       else
         klass = Generators::Default
       end
 
-      klass.generate({schema: @schema, link: @link})
-    end
-
-    private
-
-    module Generators
-      class Default
-        class << self
-          def generate(params)
-            data = {}
-            data.merge!(params[:schema].schema_example(params[:link]['schema']))
-            generate_params(data)
-          end
-
-          private
-
-          def param_name(key, prefix, array = false)
-            result = if prefix
-              "#{prefix}[#{key}]"
-            else
-              key
-            end
-
-            result += "[]" if array
-            result
-          end
-
-          def generate_params(obj, prefix = nil)
-            result = []
-            obj.each do |key,value|
-              if value.is_a?(Hash)
-                newprefix = if prefix
-                  "#{prefix}[#{key}]"
-                else
-                  key
-                end
-                result << generate_params(value, newprefix)
-              elsif value.is_a?(Array)
-                value.each do |val|
-                  result << [param_name(key, prefix, true), CGI.escape(val.to_s)].join('=')
-                end
-              else
-                next unless value # ignores parameters with empty examples
-                result << [param_name(key, prefix), CGI.escape(value.to_s)].join('=')
-              end
-            end
-            result.flatten
-          end
-        end
-      end
-
-      class JSON
-        def self.generate(params)
-          data = {}
-          data.merge!(params[:schema].schema_example(params[:link]['schema']))
-
-          result = []
-          data.sort_by {|k,_| k.to_s }.each do |key, values|
-            [values].flatten.each do |value|
-              result << [key.to_s, CGI.escape(value.to_s)].join('=')
-            end
-          end
-
-          result
-        end
-      end
+      klass.generate(schema: @schema, link: @link)
     end
   end
 end