dictum 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1abfdfd254c6440dd20d29a1f76339d413512ee5
-  data.tar.gz: 01f93d8ee750b724a6c93e4a9beabab729cadfbe
+  metadata.gz: c7497e8af6c6c8ca44b6d22efcc8d35c2e7fdced
+  data.tar.gz: 4035ae72c64eeb23ba13ca9e6cceca97750f889f
 SHA512:
-  metadata.gz: 43e9db9a4c534ffb44e4a648fff63f44a5c38565e716708dc2beff30d8cd6b31046f487f8769ccf1ebd89d74aff15145e4b51b861f5ad9847a001955c784b621
-  data.tar.gz: 96012528a2372d4bc8879367c4f64462e2209b6e9138f6ee7f5d40969910a1706e269a3e39a1d6973cdee088b6c2b4ab9c8d9c206473cb7066b6ae9af21fe591
+  metadata.gz: ba691003c2487a7871b7a2ce6af0782bb1b8655a22adddbb25fe33eba196fb4d3dc8905b291cf6dfd12781fd3c1a57adc92d2161940582fbc276c099f347bdeb
+  data.tar.gz: 42c8d20e80ca2b825e87812d208800a0406f863d255cb4ddc4d3f1646cd131bb949f51846901d361c2b1be7369a1f20357c3b9c5d666f7863c4a6ea65363f32e

data/.rubocop.yml

@@ -1,6 +1,7 @@
 AllCops:
   Exclude:
     - dictum.gemspec
+    - lib/tasks/dictum.rake
     - spec/spec_helper.rb
 
 Documentation:

data/Gemfile

@@ -3,9 +3,10 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in crf.gemspec
 gemspec
 
-gem 'rake', '~> 11.1'
-gem 'json', '~> 1.8'
+gem 'rake', '~> 12.0'
+gem 'json', '~> 2.0'
 
 group :test do
-  gem 'codeclimate-test-reporter', require: false
+  gem 'simplecov'
+  gem 'codeclimate-test-reporter', '~> 1.0.0'
 end

data/README.md

@@ -128,6 +128,25 @@ And voilà, Dictum will create a document like this in '/docs/Documentation' (se
     "no_content"
     ```
 
+# Error codes
+
+Dictum supports the documentation of the custom error codes of your API. In order to do this you need to send an array of errors with a specific format, like the following:
+
+```ruby
+ERROR_CODES = [
+  {
+    code: 1234,
+    message: 'This is a short description of the error, usually what is returned in the body of the response.',
+    description: 'This is a larger and more detailed description of the error, usually you want to show this only in the documentation'
+  }
+]
+
+# spec_helper.rb
+Dictum.error_codes(ERROR_CODES)
+```
+
+We recommend you to define your error codes in a module or class with useful methods like get(error_code) and get_all, [like this one](https://gist.github.com/alebian/1b925151b6a6acd3e4bb2ef4b5148324).
+
 # Advanced usage
 
 If you pay attention to the basic usage, you will notice that it is a lot of boilerplate if your API has a lot of endpoints, this is not DRY. Luckily you can work around it using some Rspec tricks:

data/TODO.md

@@ -1,5 +1,5 @@
 # List of TODOs
 - Don't generate documentation while running normal tests
 - Improve HTML style and generator
-- Try it for Unit Test
+- Try it for Unit Test and minitest
 - Make it more general, not only for REST APIs

data/dictum.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec)/})
 
-  spec.add_dependency 'nokogiri', '~> 1.6'
+  spec.add_dependency 'nokogiri', '~> 1.7'
 
   spec.add_development_dependency 'bundler', '>= 1.3.0', '< 2.0'
   spec.add_development_dependency 'rspec', '~> 3.4', '>= 3.4.0'

data/lib/dictum.rb

@@ -8,6 +8,8 @@ require 'tmpdir'
 module Dictum
   load 'tasks/dictum.rake' if defined?(Rails)
 
+  TEMPFILE_PATH = "#{Dir.tmpdir}/dictum_temp.json".freeze
+
   @config = {
     output_format: :markdown,
     output_path: "#{Dir.tmpdir}/docs",
@@ -73,6 +75,14 @@ module Dictum
     Documenter.instance.endpoint(arguments)
   end
 
+  ##
+  # Method used to add a new error code.
+  # @param codes_list is an array of hashes representing the code, message and description
+  #
+  def self.error_codes(codes_list)
+    codes_list.each { |error| Documenter.instance.error_code(error) }
+  end
+
   ##
   # Method that will execute tests and then save the results in the selected format
   #
@@ -88,13 +98,12 @@ module Dictum
   def self.save_to_file
     writer = nil
     output_filename = "#{@config[:output_path]}/#{@config[:output_filename]}"
-    tempfile_path = Documenter.instance.tempfile_path
 
     case @config[:output_format]
     when :markdown
-      writer = MarkdownWriter.new(output_filename, tempfile_path, @config)
+      writer = MarkdownWriter.new(output_filename, TEMPFILE_PATH, @config)
     when :html
-      writer = HtmlWriter.new(output_filename, tempfile_path, @config)
+      writer = HtmlWriter.new(output_filename, TEMPFILE_PATH, @config)
     end
 
     writer.write

data/lib/dictum/constants.rb

@@ -0,0 +1,3 @@
+module Dictum
+  MISSING_MESSAGE = 'Dictum error: data not provided.'.freeze
+end

data/lib/dictum/documenter.rb

@@ -1,5 +1,6 @@
 require 'singleton'
 require 'tmpdir'
+require_relative 'constants'
 
 module Dictum
   ##
@@ -7,13 +8,11 @@ module Dictum
   #
   class Documenter
     include Singleton
-
     attr_reader :data, :tempfile_path
-    TEMPFILE_NAME = 'dictum_temp.json'.freeze
 
     def initialize
       reset_data
-      @tempfile_path = "#{Dir.tmpdir}/#{TEMPFILE_NAME}"
+      @tempfile_path = Dictum::TEMPFILE_PATH
     end
 
     def resource(arguments = {})
@@ -36,9 +35,21 @@ module Dictum
       update_temp
     end
 
+    def error_code(error = {})
+      return if error.nil? || !error.is_a?(Hash)
+      error_hash = {
+        code: error[:code] || Dictum::MISSING_MESSAGE,
+        message: error[:message] || '',
+        description: error[:description] || ''
+      }
+      error_codes << error_hash
+      update_temp
+    end
+
     def reset_data
       @data = {
-        resources: {}
+        resources: {},
+        error_codes: []
       }
     end
 
@@ -48,6 +59,10 @@ module Dictum
       @data[:resources]
     end
 
+    def error_codes
+      @data[:error_codes]
+    end
+
     def update_temp
       File.delete(tempfile_path) if File.exist?(tempfile_path)
       file = File.open(tempfile_path, 'w+')

data/lib/dictum/html_helpers.rb

@@ -1,4 +1,5 @@
 module Dictum
+  # rubocop:disable ClassLength
   class HtmlHelpers
     BOOTSTRAP_JS = 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js'.freeze
     BOOTSTRAP_CSS = 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css'.freeze
@@ -111,6 +112,29 @@ module Dictum
         end
         answer += ">#{content}</#{name}>"
       end
+
+      def table(headers, rows)
+        return '' unless headers
+        answer = table_headers(headers)
+        answer += table_rows(rows)
+        tag('table', answer, class: 'table')
+      end
+
+      private
+
+      def table_headers(headers)
+        answer = ''
+        headers.each { |header| answer += tag('th', header) }
+        tag('tr', answer)
+      end
+
+      def table_rows(rows)
+        answer = ''
+        rows.each do |row|
+          answer += tag('tr', tag('td', row[0]) + tag('td', row[1]) + tag('td', row[2]))
+        end
+        answer
+      end
     end
   end
 end

data/lib/dictum/html_writer.rb

@@ -3,7 +3,13 @@ require 'json'
 require 'nokogiri'
 
 module Dictum
+  # rubocop:disable ClassLength
   class HtmlWriter
+    ERROR_CODE_URL = 'error_codes'.freeze
+    ERROR_CODE_TEXT = 'Error codes'.freeze
+    RESOURCES_TEXT = 'Resources'.freeze
+    BACK_TEXT = 'Back'.freeze
+
     attr_reader :temp_path, :temp_json, :output_dir, :output_file, :header_title
 
     def initialize(output_dir, temp_path, config)
@@ -28,10 +34,14 @@ module Dictum
       index.close
     end
 
+    # rubocop:disable LineLength
+    # rubocop:disable AbcSize
     def write_index
       html = HtmlHelpers.build do |b|
         content = b.jumbotron(b.title(@config[:index_title], 'title'))
+        content += b.title(RESOURCES_TEXT)
         content += b.unordered_list(resources.keys)
+        content += b.link("#{ERROR_CODE_URL}.html", b.subtitle(ERROR_CODE_TEXT)) unless error_codes.empty?
         container = b.container(b.row(content))
         b.html_header(header_title, container, @config[:inline_css])
       end
@@ -42,18 +52,23 @@ module Dictum
       resources.each do |resource_name, information|
         write_page(resource_name, information)
       end
+      write_error_codes_page unless error_codes.empty?
     end
 
     def resources
       temp_json['resources']
     end
 
+    def error_codes
+      temp_json['error_codes']
+    end
+
     def write_page(resource_name, information)
       html = HtmlHelpers.build do |b|
         content = resource_header_and_endpoints(
           resource_name, information['description'], information['endpoints'], b
         )
-        container = b.container(b.row(content) + b.row(b.button('Back')))
+        container = b.container(b.row(content) + b.row(b.button(BACK_TEXT)))
         b.html_header(header_title, container, @config[:inline_css])
       end
       write_to_file("#{output_dir}/#{resource_name.downcase}.html", html)
@@ -83,10 +98,7 @@ module Dictum
 
     def write_response(endpoint, builder)
       answer = builder.code_block('Status', endpoint['response_status'])
-      answer += write_codeblock(
-        'Response headers', endpoint['response_headers'], builder
-      ) if endpoint['response_headers']
-
+      answer += write_codeblock('Response headers', endpoint['response_headers'], builder) if endpoint['response_headers']
       if endpoint['response_body']
         param = endpoint['response_body'] == 'no_content' ? {} : endpoint['response_body']
         answer += write_codeblock('Response body', param, builder)
@@ -99,5 +111,23 @@ module Dictum
       sanitized_json = json.empty? ? {} : json
       builder.code_block(text, JSON.pretty_generate(sanitized_json))
     end
+
+    def write_error_codes_page
+      html = HtmlHelpers.build do |b|
+        content = b.title(ERROR_CODE_TEXT, 'title')
+        content += b.table(error_code_table_header, error_codes_as_rows)
+        container = b.container(b.row(content) + b.row(b.button(BACK_TEXT)))
+        b.html_header(header_title, container, @config[:inline_css])
+      end
+      write_to_file("#{output_dir}/#{ERROR_CODE_URL}.html", html)
+    end
+
+    def error_code_table_header
+      %w(Code Description Message)
+    end
+
+    def error_codes_as_rows
+      error_codes.map { |a| [a['code'], a['description'], a['message']] }
+    end
   end
 end

data/lib/dictum/markdown_writer.rb

@@ -16,6 +16,7 @@ module Dictum
       @output_file = File.open(output_path, 'a+')
       write_index
       write_temp_path
+      write_error_codes
       output_file.close
     end
 
@@ -37,6 +38,17 @@ module Dictum
       end
     end
 
+    def write_error_codes
+      return if error_codes.empty?
+      output_file.puts "# Error codes"
+      output_file.puts "|Code|Message|Description|"
+      output_file.puts "|----|----|----|"
+      error_codes.each do |error|
+        output_file.puts "|#{error['code']}|#{error['message']}|#{error['description']}|"
+      end
+      output_file.puts "\n"
+    end
+
     def write_endpoints(endpoints)
       endpoints.each do |endpoint|
         output_file.puts "## #{endpoint['http_verb']} #{endpoint['endpoint']}\n\n"
@@ -70,5 +82,9 @@ module Dictum
       output_file.puts "\#\#\# #{subtitle}:"
       output_file.puts "```json\n#{JSON.pretty_generate(sanitized_contents)}\n```\n\n"
     end
+
+    def error_codes
+      temp_json['error_codes']
+    end
   end
 end

data/lib/dictum/version.rb

@@ -1,3 +1,3 @@
 module Dictum
-  VERSION = '0.0.5'.freeze
+  VERSION = '0.0.6'.freeze
 end

data/lib/tasks/default_initializer

@@ -3,4 +3,5 @@ Dictum.configure do |config|
   config.root_path = Rails.root
   config.output_filename = 'Documentation'
   config.output_format = :markdown
+  config.index_title = 'MYAPP API documentation'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dictum
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Alejandro Bezdjian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-26 00:00:00.000000000 Z
+date: 2017-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -124,6 +124,7 @@ files:
 - example.gif
 - example.md
 - lib/dictum.rb
+- lib/dictum/constants.rb
 - lib/dictum/documenter.rb
 - lib/dictum/html_helpers.rb
 - lib/dictum/html_writer.rb