dictum 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d6c5ff3c6e60436b079a7686e5ac902c0667dd16
+  data.tar.gz: 1e01d5c17f6c352d49f3b701dc6f574ad5bbad81
+SHA512:
+  metadata.gz: 5d10b7d5b8a4f91682e0a40424bae391b1c12269e6b4b6080d90cb73ebe9e8ec62a26529b2e002df6b8f189d2fa5317f76db87d67fdbb1176d578cd4842512c5
+  data.tar.gz: af6203c9ea677dca51c9fbf1fe14b7dc451d36ef3c745a51f795ce7d209c603a1df1f0198dfa150b24254734956e7858720486e5350b672197b20aa301a84c0b

data/.gitignore

@@ -0,0 +1,70 @@
+# Created by https://www.gitignore.io/api/ruby,osx
+
+*.log
+.byebug_history
+/spec/test_files
+*.test
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+### OSX ###
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  Exclude:
+    - dictum.gemspec
+
+Documentation:
+  Enabled: false
+
+LineLength:
+  Max: 99
+
+FrozenStringLiteralComment:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,33 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - 2.2.4
+  - 2.3.0
+
+install:
+  - gem install bundler
+  - bundle install --retry=3
+
+script:
+  - bundle exec rspec
+  - bundle exec rubocop -R --format simple
+
+addons:
+    code_climate:
+        repo_token: 18ae4433a073ee0e00127ab95c826ac5552d3b14d712aa70a231e9e3903f84d5
+
+os:
+  - linux
+  - osx
+
+matrix:
+  exclude:
+    - rvm: 2.2
+      os: osx
+    - rvm: 2.2.4
+      os: osx
+    - rvm: 2.3.0
+      os: osx

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in crf.gemspec
+gemspec
+
+gem 'rake', '~> 11.1'
+gem 'json', '~> 1.8'
+
+group :test do
+  gem 'codeclimate-test-reporter', require: false
+end

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Alejandro Bezdjian, aka alebian
+
+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,181 @@
+# Dictum - Document your Rails APIs
+[![Gem Version](https://badge.fury.io/rb/dictum.svg)](https://badge.fury.io/rb/dictum)
+[![Dependency Status](https://gemnasium.com/badges/github.com/alebian/dictum.svg)](https://gemnasium.com/github.com/alebian/dictum)
+[![Build Status](https://travis-ci.org/alebian/dictum.svg)](https://travis-ci.org/alebian/dictum)
+[![Code Climate](https://codeclimate.com/github/alebian/dictum/badges/gpa.svg)](https://codeclimate.com/github/alebian/dictum)
+[![Test Coverage](https://codeclimate.com/github/alebian/dictum/badges/coverage.svg)](https://codeclimate.com/github/alebian/dictum/coverage)
+[![Issue Count](https://codeclimate.com/github/alebian/dictum/badges/issue_count.svg)](https://codeclimate.com/github/alebian/dictum)
+[![Inline docs](http://inch-ci.org/github/alebian/dictum.svg)](http://inch-ci.org/github/alebian/dictum)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dictum'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install dictum
+
+## Usage
+
+First you need to set a configuration file inside /config/initializers/dictum.rb
+
+```ruby
+Dictum.configure do |config|
+  config.output_path = Rails.root.join('docs')
+  config.root_path = Rails.root
+  config.output_filename = 'Documentation'
+  # config.output_format = :markdown
+  # test_suite = :rspec
+end
+```
+
+Then you can use Dictum in the most verbose and fully customizable way like this in your tests:
+
+```ruby
+require 'rails_helper'
+
+describe V1::MyResourceController do
+  Dictum.resource(
+    name: 'MyResource',
+    description: 'This is MyResource description.'
+  )
+
+  describe '#some_method' do
+    context 'some context for my resource' do
+      it 'returns status ok' do
+        get :index
+        Dictum.endpoint(
+          resource: 'MyResource',
+          endpoint: '/api/v1/my_resource/:id',
+          http_verb: 'POST',
+          description: 'Some description of the endpoint.',
+          request_headers: { 'AUTHORIZATION' => 'user_token',
+                             'Content-Type' => 'application/json',
+                             'Accept' => 'application/json' },
+          request_path_parameters: { id: 1, page: 1 },
+          request_body_parameters: { some: 'parameter' },
+          response_headers: { 'some_header' => 'some_header_value' },
+          response_status: response.status,
+          response_body: response_body
+        )
+        expect(response_status).to eq(200)
+      end
+    end
+  end
+end
+```
+Most parameters are not mandatory, and as you can see, writing all of these for each endpoint can add a lot of unnecessary boilerplate. But since you know everything the method receives you can customize the usage anyway you like, for example:
+
+```ruby
+require 'rails_helper'
+
+describe V1::MyResourceController do
+  Dictum.resource(
+    name: 'MyResource',
+    description: 'This is MyResource description.'
+  )
+
+  after(:each) do |test|
+    if test.metadata[:dictum]
+      Dictum.endpoint(
+        resource: test.metadata[:described_class].to_s.gsub('V1::', '').gsub('Controller', ''),
+        endpoint: request.fullpath,
+        http_verb: request.env['REQUEST_METHOD'],
+        description: test.metadata[:dictum_description],
+        request_headers: { 'AUTHORIZATION' => 'user_token',
+                           'Content-Type' => 'application/json',
+                           'Accept' => 'application/json' },
+        request_path_parameters: request.env['action_dispatch.request.path_parameters'].except(:controller, :action),
+        request_body_parameters: request.env['action_dispatch.request.parameters'].except('controller', 'action'),
+        response_headers: response.headers,
+        response_status: response.status,
+        response_body: response_body
+    end
+  end
+
+  describe '#some_method' do
+    context 'some context for my resource' do
+      it 'returns status ok', dictum: true, dictum_description: 'Some description of the endpoint.' do
+        get :index
+        expect(response_status).to eq(200)
+      end
+    end
+  end
+end
+```
+
+Then execute:
+
+    $ bundle exec dictum
+
+Both ways Dictum will create a document like this:
+
+    # Index
+    - MyResource
+
+    # MyResource
+    This is MyResource description.
+
+    ## GET /api/v1/my_resource
+
+    ### Description:
+    Some description of the endpoint.
+
+    ### Request headers:
+    ```json
+    {
+      "AUTHORIZATION" : "user_token",
+      "Content-Type" : "application/json",
+      "Accept" : "application/json"
+    }
+    ```
+
+    ### Response status:
+    200
+
+    ### Response body:
+    ```json
+    "no_content"
+    ```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Run rubocop lint (`rubocop -R --format simple`)
+5. Run rspec tests (`bundle exec rspec`)
+6. Push your branch (`git push origin my-new-feature`)
+7. Create a new Pull Request
+
+## License
+
+**Dictum** is available under the MIT [license](https://raw.githubusercontent.com/alebian/dictum/master/LICENSE.md).
+
+    Copyright (c) 2016 Alejandro Bezdjian, aka alebian
+
+    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/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/TODO.md

@@ -0,0 +1,7 @@
+# List of TODOs
+- Add some tests
+- Don't generate documentation while running normal tests
+- HTML ducumentation option
+- Dir.tempdir problems outside Rails
+- Try it for Unit Test
+- Make it more general, not only for REST APIs

data/dictum.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dictum/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'dictum'
+  spec.version       = Dictum::VERSION
+  spec.authors       = ['Alejandro Bezdjian']
+  spec.email         = 'alebezdjian@gmail.com'
+  spec.date          = Date.today
+  spec.summary       = 'Document your APIs.'
+  spec.description   = 'Create automatic documentation of your API endpoints through your tests.'
+  spec.platform      = Gem::Platform::RUBY
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec)/}) }
+  spec.require_paths = ['lib']
+  spec.homepage      = 'https://github.com/alebian/dictum'
+  spec.license       = 'MIT'
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec)/})
+
+  spec.add_development_dependency 'bundler', '>= 1.3.0', '< 2.0'
+  spec.add_development_dependency 'rspec', '~> 3.4', '>= 3.4.0'
+  spec.add_development_dependency 'byebug', '~> 8.0', '>= 8.0.0' if RUBY_VERSION >= '2.0.0'
+  spec.add_development_dependency 'rubocop', '~> 0.38', '>= 0.38.2'
+end

data/lib/dictum.rb

@@ -0,0 +1,73 @@
+require 'dictum/version'
+require 'dictum/documenter'
+require 'dictum/markdown_writer'
+
+module Dictum
+  load 'tasks/dictum.rake' if defined?(Rails)
+
+  @config = {
+    output_format: :markdown,
+    output_path: '/tmp/docs',
+    root_path: '/tmp',
+    test_suite: :rspec,
+    output_filename: 'Documentation'
+  }
+
+  def self.configure
+    yield self
+  end
+
+  def self.output_format=(style)
+    @config[:output_format] = style
+  end
+
+  def self.output_path=(folder)
+    @config[:output_path] = folder
+  end
+
+  def self.root_path=(folder)
+    @config[:root_path] = folder
+  end
+
+  def self.test_suite=(suite)
+    @config[:test_suite] = suite
+  end
+
+  def self.output_filename=(file)
+    @config[:output_filename] = file
+  end
+
+  ##
+  # Method used to create a new resource
+  #
+  def self.resource(arguments)
+    Documenter.instance.resource(arguments)
+  end
+
+  ##
+  # Method used to create a new endpoint of a resource
+  #
+  def self.endpoint(arguments)
+    Documenter.instance.endpoint(arguments)
+  end
+
+  ##
+  # Method that will execute tests and then save the results in the selected format
+  #
+  def self.document
+    Dir.mkdir(@config[:output_path]) unless Dir.exist?(@config[:output_path])
+    Documenter.instance.reset_resources
+    system "bundle exec rspec #{@config[:root_path]}" if @config[:test_suite] == :rspec
+    save_to_file
+  end
+
+  def self.save_to_file
+    writer = nil
+    case @config[:output_format]
+    when :markdown
+      writer = MarkdownWriter.new("#{@config[:output_path]}/#{@config[:output_filename]}.md",
+                                  Documenter.instance.tempfile_path)
+    end
+    writer.write
+  end
+end

data/lib/dictum/documenter.rb

@@ -0,0 +1,59 @@
+require 'singleton'
+
+module Dictum
+  ##
+  # Singleton class that gathers the documentation and stores it as a hash/json
+  #
+  class Documenter
+    include Singleton
+    attr_reader :resources, :tempfile_path
+
+    def initialize
+      @resources = {}
+      @tempfile_path = '/tmp/dictum_temp.json'
+    end
+
+    def resource(arguments = {})
+      name = arguments[:name]
+      return if name.nil?
+      @resources[name] ||= {}
+      @resources[name][:description] = arguments[:description] if arguments[:description]
+      @resources[name][:endpoints] ||= []
+      update_temp
+    end
+
+    def endpoint(arguments = {})
+      resource = arguments[:resource]
+      endpoint = arguments[:endpoint]
+      return if resource.nil? || endpoint.nil?
+      resource(name: arguments[:resource]) unless @resources.key? arguments[:resource]
+      @resources[resource][:endpoints] << arguments_hash(arguments)
+      update_temp
+    end
+
+    def reset_resources
+      @resources = {}
+    end
+
+    private
+
+    def update_temp
+      File.delete(tempfile_path) if File.exist?(tempfile_path)
+      file = File.open(tempfile_path, 'w+')
+      file.write(JSON.generate(@resources))
+      file.close
+    end
+
+    def arguments_hash(arguments)
+      { endpoint: arguments[:endpoint],
+        description: arguments[:description],
+        http_verb: arguments[:http_verb] || '',
+        request_headers: arguments[:request_headers],
+        request_path_parameters: arguments[:request_path_parameters],
+        request_body_parameters: arguments[:request_body_parameters],
+        response_status: arguments[:response_status],
+        response_headers: arguments[:response_headers],
+        response_body: arguments[:response_body] }
+    end
+  end
+end

data/lib/dictum/markdown_writer.rb

@@ -0,0 +1,73 @@
+require 'json'
+
+module Dictum
+  class MarkdownWriter
+    attr_reader :temp_path, :temp_json, :output_path, :output_file
+
+    def initialize(output_path, temp_path)
+      @output_path = output_path
+      File.delete(output_path) if File.exist?(output_path)
+      @temp_path = temp_path
+      @temp_json = JSON.parse(File.read(temp_path))
+    end
+
+    def write
+      @output_file = File.open(output_path, 'a+')
+      write_index
+      write_temp_path
+      output_file.close
+      File.delete(temp_path) if File.exist?(temp_path)
+    end
+
+    private
+
+    def write_index
+      output_file.puts '# Index'
+      @temp_json.each do |resource_name, _information|
+        output_file.puts "- #{resource_name}"
+      end
+      output_file.puts "\n"
+    end
+
+    def write_temp_path
+      @temp_json.each do |resource_name, information|
+        output_file.puts "# #{resource_name}"
+        output_file.puts "#{information['description']}\n\n"
+        write_endpoints(information['endpoints'])
+      end
+    end
+
+    def write_endpoints(endpoints)
+      endpoints.each do |endpoint|
+        output_file.puts "## #{endpoint['http_verb']} #{endpoint['endpoint']}\n\n"
+        write_endpoint_description(endpoint)
+        write_endpoint_response(endpoint)
+      end
+    end
+
+    def write_endpoint_description(endpoint)
+      print_subsubtitle('Description', endpoint['description'])
+      print_subsubtitle_json('Request headers', endpoint['request_headers'])
+      print_subsubtitle_json('Path parameters', endpoint['request_path_parameters'])
+      print_subsubtitle_json('Body Parameters', endpoint['request_body_parameters'])
+    end
+
+    def write_endpoint_response(endpoint)
+      print_subsubtitle('Response status', endpoint['response_status'])
+      print_subsubtitle_json('Response headers', endpoint['response_headers'])
+      print_subsubtitle_json('Response body', endpoint['response_body'])
+    end
+
+    def print_subsubtitle(subtitle, contents)
+      return if !subtitle.present? || !contents.present?
+      output_file.puts "\#\#\# #{subtitle}:"
+      output_file.puts "#{contents}\n\n"
+    end
+
+    def print_subsubtitle_json(subtitle, contents)
+      return if !subtitle.present? || !contents.present?
+      output_file.puts "\#\#\# #{subtitle}:"
+      output_file.puts "```json\n#{JSON.pretty_generate(contents)}\n```\n\n"
+    end
+  end
+end

data/lib/dictum/version.rb

@@ -0,0 +1,3 @@
+module Dictum
+  VERSION = '0.0.2'.freeze
+end

data/lib/tasks/dictum.rake

@@ -0,0 +1,8 @@
+require 'rake'
+
+namespace :dictum do
+  desc 'Starts the documenting process'
+  task document: :environment do
+    system 'bundle exec rails runner -e test Dictum.document'
+  end
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: dictum
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Alejandro Bezdjian
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.38.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.38.2
+description: Create automatic documentation of your API endpoints through your tests.
+email: alebezdjian@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- TODO.md
+- dictum.gemspec
+- lib/dictum.rb
+- lib/dictum/documenter.rb
+- lib/dictum/markdown_writer.rb
+- lib/dictum/version.rb
+- lib/tasks/dictum.rake
+homepage: https://github.com/alebian/dictum
+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: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Document your APIs.
+test_files: []
+has_rdoc: