jdoc 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 32fedb39817ea5f19c6fdd4f058715150348b50d
-  data.tar.gz: 046bbaaf9e08fb214ee5eca23c80c3f73ab34ebf
+  metadata.gz: 28bc94f091b81a3e04e106f675c00f8940275841
+  data.tar.gz: 8402b0802f2e5a2a59645b9d5140843964725374
 SHA512:
-  metadata.gz: f67afb16cbcdea69460fd56253d371b84b84aacb88bdea7115331c8fd9e9b0f4633499cef1ed853f0691de56d569eb9834bc869b2211db05051b7a7c80f2515a
-  data.tar.gz: 521e04c49a756ae3e3e86058b0c070c49b67f3be906fd21adc8219516277352e1e81a808b352c92c75f39a7c8325c938106b3c922f0e6f1b218f1d7455f3cf5c
+  metadata.gz: c5c1fe253da35df82c05ee7628ddeeebcb1e18dccf045006ddc75335304c70352c637480528df9401093c9d8a3f7e8cc7ea3ff86ccdef39673c2ba5ad79c00cd
+  data.tar.gz: 6a9df487e28224d36af6b1092f9c92c707376df84fa61640c45a96311af64e217fc4e0449080ba173e623c27c647d7acd78b610f2f2f6f690bb1fc5d5429bdb2

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.2
+* Add generator options to change template
+* Add request parameters for each endpoint
+
 ## 0.3.1
 * Add error handling for ExampleNotFound
 

data/example-api-documentation.md

@@ -26,7 +26,7 @@ An app is a program to be deployed.
  * unique name of app
  * Example: `"example"`
  * Type: string
- * Patern: `(?-mix:^[a-z][a-z0-9-]{3,50}$)`
+ * Pattern: `(?-mix:^[a-z][a-z0-9-]{3,50}$)`
 * private
  * true if this resource is private use
  * Example: `false`
@@ -43,6 +43,12 @@ An app is a program to be deployed.
 ### POST /apps
 Create a new app.
 
+* name
+ * unique name of app
+ * Example: `"example"`
+ * Type: string
+ * Pattern: `(?-mix:^[a-z][a-z0-9-]{3,50}$)`
+
 ```
 POST /apps HTTP/1.1
 Content-Type: application/json
@@ -143,6 +149,12 @@ Content-Type: application/json
 ### PATCH /apps/:id
 Update an existing app.
 
+* name
+ * unique name of app
+ * Example: `"example"`
+ * Type: string
+ * Pattern: `(?-mix:^[a-z][a-z0-9-]{3,50}$)`
+
 ```
 PATCH /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
 Content-Type: application/json
@@ -175,6 +187,11 @@ Content-Type: application/json
 ### POST /apps/:id/files
 Upload an attachment file for an app
 
+* file
+ * an attachment of app
+ * Example: `"... contents of file ..."`
+ * Type: string
+
 ```
 POST /apps/01234567-89ab-cdef-0123-456789abcdef/files HTTP/1.1
 Content-Type: multipart/form-data; boundary=---BoundaryX

data/lib/jdoc/generator.rb

@@ -1,42 +1,7 @@
 module Jdoc
   class Generator
-    HTML_TEMPLATE_PATH = File.expand_path("../../../template.html.erb", __FILE__)
-    MARKDOWN_TEMPLATE_PATH = File.expand_path("../../../template.md.erb", __FILE__)
-
-    class << self
-      # @return [Erubis::Eruby]
-      def markdown_renderer
-        @markdown_renderer ||= Erubis::Eruby.new(markdown_template)
-      end
-
-      # @return [Erubis::Eruby]
-      def html_renderer
-        @html_renderer ||= Erubis::Eruby.new(html_template)
-      end
-
-      def redcarpet
-        @redcarpet ||= Redcarpet::Markdown.new(
-          Redcarpet::Render::HTML.new(
-            filter_html: true,
-            hard_wrap: true,
-            with_toc_data: true,
-          ),
-          autolink: true,
-          fenced_code_blocks: true,
-          no_intra_emphasis: true,
-        )
-      end
-
-      # @return [String] ERB template
-      def markdown_template
-        File.read(MARKDOWN_TEMPLATE_PATH)
-      end
-
-      # @return [String] ERB template
-      def html_template
-        File.read(HTML_TEMPLATE_PATH)
-      end
-    end
+    DEFAULT_HTML_TEMPLATE_PATH = File.expand_path("../../../template.html.erb", __FILE__)
+    DEFAULT_MARKDOWN_TEMPLATE_PATH = File.expand_path("../../../template.md.erb", __FILE__)
 
     # Utility wrapper for Jdoc::Generator#call
     # @return [String]
@@ -46,21 +11,26 @@ module Jdoc
 
     # @param schema [Hash] JSON Schema represented as a Hash
     # @param html [true, false] Pass true to render HTML docs
-    def initialize(schema, html: false)
+    # @param html_template_path [String] Path to ERB template to render HTML
+    # @param Markdown_template_path [String] Path to ERB template to render Markdown
+    def initialize(schema, html: false, html_template_path: nil, markdown_template_path: nil)
       @raw_schema = schema
       @html = html
+      @html_template_path = html_template_path
+      @markdown_template_path = markdown_template_path
     end
 
     # Generates Markdown or HTML documentation from JSON schema
     # @note Add some fix to adapt to GitHub anchor style
-    # @return [String]
+    # @return [String] Generated text
     def call
-      result = self.class.markdown_renderer.result(schema: schema)
+      markdown = markdown_renderer.result(schema: schema)
       if @html
-        result = self.class.html_renderer.result(body: self.class.redcarpet.render(result))
-        result.gsub(/id="(.+)"/) {|text| text.tr("/:", "") }
+        html = markdown_parser.render(markdown)
+        html =  html_renderer.result(body: html)
+        html.gsub(/id="(.+)"/) {|text| text.tr("/:", "") }
       else
-        result
+        markdown
       end
     rescue Jdoc::Link::ExampleNotFound => exception
       abort("Error: #{exception.to_s}")
@@ -68,10 +38,53 @@ module Jdoc
 
     private
 
+    # @return [Erubis::Eruby] Renderer to render HTML that takes HTML string
+    def html_renderer
+      Erubis::Eruby.new(html_template)
+    end
+
+    # @returns [String] Path to ERB template to render HTML
+    def html_template_path
+      @html_template_path || DEFAULT_HTML_TEMPLATE_PATH
+    end
+
+    def html_template
+      File.read(html_template_path)
+    end
+
+    # @return [Redcarpet::Markdown] Markdown parser to convert Markdown into HTML
+    def markdown_parser
+      Redcarpet::Markdown.new(
+        Redcarpet::Render::HTML.new(
+          filter_html: true,
+          hard_wrap: true,
+          with_toc_data: true,
+        ),
+        autolink: true,
+        fenced_code_blocks: true,
+        no_intra_emphasis: true,
+      )
+    end
+
+    # @return [Erubis::Eruby] Renderer to render Markdown that takes schema data
+    def markdown_renderer
+      Erubis::Eruby.new(markdown_template)
+    end
+
+    # @return [String] Content of specified Markdown template
+    def markdown_template
+      File.read(markdown_template_path)
+    end
+
+    # @return [String] Path to ERB template to render Markdown
+    def markdown_template_path
+      @markdown_template_path || DEFAULT_MARKDOWN_TEMPLATE_PATH
+    end
+
     # @return [Jdoc::Schema]
     # @raise [JsonSchema::SchemaError] Raises if given invalid JSON Schema
     def schema
-      @schema ||= Jdoc::Schema.new(@raw_schema)
+      Jdoc::Schema.new(@raw_schema)
     end
   end
 end

data/lib/jdoc/link.rb

@@ -122,7 +122,7 @@ module Jdoc
     # @return [Hash] Example request parameters for this endpoint
     def request_parameters
       @request_parameters ||= begin
-        if has_schema_in_link?
+        if request_schema
           RequestGenerator.call(request_schema.properties)
         else
           {}
@@ -130,6 +130,19 @@ module Jdoc
       end
     end
 
+    # @return [Array<Jdoc::Property>] Properties defined in this link's schema property.
+    def request_properties
+      @request_properties ||= begin
+        if request_schema
+          request_schema.properties.map do |name, schema|
+            Property.new(name: name, schema: schema)
+          end
+        else
+          []
+        end
+      end
+    end
+
     # @return [true, false] True if this endpoint must have request body
     def has_request_body?
       ["PATCH", "POST", "PUT"].include?(method)
@@ -166,7 +179,7 @@ module Jdoc
 
     # @return [JsonSchema::Schema] Request schema for this link
     def request_schema
-      @raw_link.schema || @raw_link.parent
+      @raw_link.schema
     end
 
     # @return [Json::Link::Resource]
@@ -188,11 +201,6 @@ module Jdoc
       end
     end
 
-    # @return [true, false] True if a given link has a schema property
-    def has_schema_in_link?
-      !!@raw_link.schema
-    end
-
     # @return [true, false] True if response is intended to be list data
     def has_list_data?
       @raw_link.rel == "instances"

data/lib/jdoc/property.rb

@@ -15,7 +15,7 @@ module Jdoc
         Example: example,
         Type: type,
         Format: format,
-        Patern: pattern,
+        Pattern: pattern,
         ReadOnly: read_only,
       }.reject {|key, value| value.nil? }
     end

data/lib/jdoc/version.rb

@@ -1,3 +1,3 @@
 module Jdoc
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/template.md.erb

@@ -26,6 +26,18 @@
 ### <%= link.endpoint %>
 <%= link.description %>
 
+<% if link.request_schema %>
+<% link.request_properties.each do |property| %>
+* <%= property.name %>
+<% if property.description %>
+ * <%= property.description %>
+<% end %>
+<% property.options.each do |key, value| %>
+ * <%= key %>: <%= value %>
+<% end %>
+<% end %>
+
+<% end %>
 ```
 <%= link.method %> <%= link.example_path %><%= link.query_string %> HTTP/1.1
 <%= "Content-Type: #{link.content_type}\n" if link.has_request_body? -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jdoc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Ryo Nakamura