dictum 0.0.6.1 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a02ebef46c17074054a5eb070123e848b6cbf5a
-  data.tar.gz: 78f159c2ff53aa9a551b1e09e29e3b25d5cc47ce
+  metadata.gz: 8a239ef90058a4c5862a7a9d3b0126a4234bf75f
+  data.tar.gz: 6d423a9f7b16eec1395d577c9932f9ee097e5261
 SHA512:
-  metadata.gz: f41ea433b442874c36f3802921a0208884cbf9003db0a2079f505091ea042de69b1b1836ab76e162c40d050af069b65fb08d08c100485e9e6fdb94e98cbabf6e
-  data.tar.gz: 3c5529f00b851bc451d3e068532440c0311c475c08662edba53ab59cc127e62e7c110c0d327cebbcda4f2570a19547d67bfba1f2a4584bb6514eb22ccb9eae40
+  metadata.gz: 3507289d2b6483ec1409ef2b80fe78ad521a4bd0e5ba5b4368cb3edf8f843a3eafc666a4f1e5fb5ae442404006fa1b253b74c6e7dc41bfb9d1275eaac25c983b
+  data.tar.gz: 6a077591d19407ff3a3e6eb208673b640884458433e1b5cb238a6ede037382204362194fc82ae8dfa3147875995ace6f0d09a9cc607d34626d4d43ff39141bf1

data/CHANGELOG.md

@@ -0,0 +1,80 @@
+
+## Change log
+
+### [0.0.7]
+
+#### Added
+
+- Changelog.
+
+#### Changed
+
+- Moved advanced usage as default usage in README.
+- Fixed how markdown documentation file was deleted.
+
+### [0.0.6.1]
+
+#### Added
+
+- Error codes in markdown writer.
+- Error codes in README.
+
+#### Changed
+
+- Upgraded some gems versions.
+
+#### Removed
+
+- Ruby 2.0.0 version from .travis.yml.
+
+### [0.0.6]
+
+#### Added
+
+- Error code feature.
+- Markdown example to README.
+- Rake configuration installer.
+- Possibility to change index and header titles.
+- Possibility to use inline css.
+
+#### Changed
+
+- Upgraded some gems versions.
+
+#### Removed
+
+- Ruby 1.9.3 version from .travis.yml.
+
+### [0.0.5]
+
+#### Added
+
+- HTML helpers tests.
+- Documenter and Dictum tests.
+- Arguments validations in writers.
+- Writers tests.
+
+### [0.0.4]
+
+#### Added
+
+- HTML writer.
+- CodeCoverage badge.
+
+### [0.0.3]
+
+#### Changed
+
+- Modified README to be more descriptive.
+
+### [0.0.2]
+
+#### Added
+
+- First release. Only markdown writer.
+
+### [0.0.1]
+
+#### Added
+
+- `dictum` gem.

data/Gemfile

@@ -1,12 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in crf.gemspec
+# Specify your gem's dependencies in dictum.gemspec
 gemspec
-
-gem 'json', '~> 2.0'
-gem 'rake', '~> 12.0'
-
-group :test do
-  gem 'codeclimate-test-reporter', '~> 1.0.0'
-  gem 'simplecov'
-end

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Alejandro Bezdjian, aka alebian
+Copyright (c) 2017 Wolox
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,11 +1,11 @@
-# Dictum - Document your Rails APIs
+# Dictum
 [![Gem Version](https://badge.fury.io/rb/dictum.svg)](https://badge.fury.io/rb/dictum)
 [![Dependency Status](https://gemnasium.com/badges/github.com/Wolox/dictum.svg)](https://gemnasium.com/github.com/Wolox/dictum)
 [![Build Status](https://travis-ci.org/Wolox/dictum.svg)](https://travis-ci.org/Wolox/dictum)
 [![Code Climate](https://codeclimate.com/github/Wolox/dictum/badges/gpa.svg)](https://codeclimate.com/github/Wolox/dictum)
 [![Test Coverage](https://codeclimate.com/github/Wolox/dictum/badges/coverage.svg)](https://codeclimate.com/github/Wolox/dictum/coverage)
-[![Issue Count](https://codeclimate.com/github/Wolox/dictum/badges/issue_count.svg)](https://codeclimate.com/github/Wolox/dictum)
-[![Inline docs](http://inch-ci.org/github/Wolox/dictum.svg)](http://inch-ci.org/github/Wolox/dictum)
+
+Create automatic documentation of your Rails APIs.
 
 ## Installation
 
@@ -23,26 +23,15 @@ Or install it yourself as:
 
     $ gem install dictum
 
-## Basic usage
+## Usage
 
-First run:
+First, run:
 
     $ bundle exec rake dictum:configure [PATH_TO_HELPER_FILE]
 
-This will create a basic Rspec configuration in 'spec/support/spec_helper.rb' or in PATH_TO_HELPER_FILE. Also it will create a configuration file inside /config/initializers/dictum.rb
-
-```ruby
-# /config/initializers/dictum.rb
-Dictum.configure do |config|
-  config.output_path = Rails.root.join('docs')
-  config.root_path = Rails.root
-  config.output_filename = 'Documentation'
-  config.output_format = :markdown
-  config.index_title = 'My Documentation Title'
-end
-```
+This will create a basic Rspec configuration for Dictum in `spec/support/spec_helper.rb` or `PATH_TO_HELPER_FILE`, along with Dictum's initializer file (`/config/initializers/dictum.rb`).
 
-Then you can use Dictum in the most verbose and fully customizable way like this in your tests:
+To document an endpoint, you have to append `dictum: true` to your controller's `it` statements, as shown below:
 
 ```ruby
 # spec/controllers/my_resource_controller_spec.rb
@@ -56,22 +45,8 @@ describe V1::MyResourceController do
 
   describe '#some_method' do
     context 'some context for my resource' do
-      it 'returns status ok' do
+      it 'returns status ok', dictum: true, dictum_description: 'This optional property exists to add a description to the endpoint.' 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
@@ -83,50 +58,7 @@ Then execute:
 
     $ bundle exec rake dictum:document
 
-And voilà, Dictum will create a document like this in '/docs/Documentation' (see [example.md](https://github.com/Wolox/dictum/blob/master/example.md)):
-
-    # My Documentation Title
-    - MyResource
-
-    # MyResource
-    This is MyResource description.
-
-    ## POST /api/v1/my_resource
-
-    ### Description:
-    Some description of the endpoint.
-
-    ### Request headers:
-    ```json
-    {
-      "AUTHORIZATION" : "user_token",
-      "Content-Type" : "application/json",
-      "Accept" : "application/json"
-    }
-    ```
-
-    ### Path parameters:
-    ```json
-    { "id": 1, "page": 1 }
-    ```
-
-    ### Body parameters:
-    ```json
-    { "some": "parameter" }
-    ```
-
-    ### Response headers:
-    ```json
-    { "some_header": "some_header_value" }
-    ```
-
-    ### Response status:
-    200
-
-    ### Response body:
-    ```json
-    "no_content"
-    ```
+And voilà, Dictum will create a document like [this](https://github.com/Wolox/dictum/blob/master/example.md) in `/docs/Documentation.md`.
 
 # Error codes
 
@@ -147,36 +79,10 @@ 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:
 
-```ruby
-# spec/rails_helper.rb
-RSpec.configure do |config|
-  config.after(:each) do |test|
-    if test.metadata[:dictum]
-      Dictum.endpoint(
-      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
-end
-```
+## Descriptive usage
 
-A file similar (and more complete) to that one is created when you run the rake dictum:configure task.
+Also, if you prefer to have more control over your endpoints documentation, you can use Dictum in the most verbose and fully customizable way, as shown below:
 
 ```ruby
 # spec/controllers/my_resource_controller_spec.rb
@@ -190,17 +96,28 @@ describe V1::MyResourceController do
 
   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
+      it 'returns status ok' do
         get :index
+        Dictum.endpoint(
+          resource: 'MyResource',
+          endpoint: '/api/v1/my_resource/:id',
+          http_verb: 'POST',
+          description: 'This optional property exists to add a description to 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
 ```
-
-This is how your controller test should look now, much better.
-
 # Dynamic HTML documentation
 
 So far so good, but your team needs to read the documentation everytime you update it, and sending the documentation file to them doesn't seem too practical. Instead you can use the HTML version of Dictum and generate static views with the content. Here is a very basic example of what you can do to generate the views and routes dynamycally:
@@ -264,7 +181,7 @@ This project is maintained by [Alejandro Bezdjian](https://github.com/alebian) a
 
 **Dictum** is available under the MIT [license](https://raw.githubusercontent.com/Wolox/dictum/master/LICENSE.md).
 
-    Copyright (c) 2016 Alejandro Bezdjian, aka alebian
+    Copyright (c) 2017 Wolox
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal

data/dictum.gemspec

@@ -2,6 +2,7 @@
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dictum/version'
+require 'date'
 
 Gem::Specification.new do |spec|
   spec.name          = 'dictum'
@@ -20,9 +21,13 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec)/})
 
   spec.add_dependency 'nokogiri', '>= 1.3.3'
+  spec.add_dependency 'json', '~> 2.0'
+  spec.add_dependency 'rake', '~> 12.0'
 
   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.40', '>= 0.40.0'
+  spec.add_development_dependency 'rubocop', '~> 0.48', '>= 0.48.0'
+  spec.add_development_dependency 'codeclimate-test-reporter', '~> 1.0.0'
+  spec.add_development_dependency 'simplecov'
 end

data/example.md

@@ -7,7 +7,7 @@ This is MyResource description.
 ## POST /api/v1/my_resource
 
 ### Description:
-Some description of the endpoint.
+This optional property exists to add a description to the endpoint.
 
 ### Request headers:
 ```json

data/lib/dictum/html_writer.rb

@@ -123,7 +123,7 @@ module Dictum
     end
 
     def error_code_table_header
-      %w(Code Description Message)
+      %w[Code Description Message]
     end
 
     def error_codes_as_rows

data/lib/dictum/markdown_writer.rb

@@ -6,7 +6,7 @@ module Dictum
 
     def initialize(output_path, temp_path, config)
       @output_path = "#{output_path}.md"
-      File.delete(output_path) if File.exist?(output_path)
+      File.delete(@output_path) if File.exist?(@output_path)
       @temp_path = temp_path
       @temp_json = JSON.parse(File.read(temp_path))
       @config = config

data/lib/dictum/version.rb

@@ -1,3 +1,3 @@
 module Dictum
-  VERSION = '0.0.6.1'.freeze
+  VERSION = '0.0.7'.freeze
 end

data/lib/tasks/default_configuration

@@ -1,18 +1,24 @@
 
+DEFAULT_REQUEST_HEADERS = {
+  'AUTHORIZATION' => 'user_token',
+  'Content-Type' => 'application/json',
+  'Accept' => 'application/json'
+}
+
 RSpec.configure do |config|
   config.after(:each) do |test|
     if test.metadata[:dictum]
     Dictum.endpoint(
-      resource: test.metadata[:described_class].to_s.gsub('V1::', '').gsub('Controller', ''),
+      resource: test.metadata[:described_class].to_s.split('::').last.gsub('Controller', ''),
       endpoint: request.fullpath,
       http_verb: request.env['REQUEST_METHOD'],
       description: test.metadata[:dictum_description],
-      request_headers: test.metadata[:dictum_no_auth] ? DEFAULT_REQUEST_HEADERS.except('AUTHORIZATION') : DEFAULT_REQUEST_HEADERS,
+      request_headers: DEFAULT_REQUEST_HEADERS,
       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['Location'] ? { 'Location' => response.headers['Location'] } : nil,
+      response_headers: response.headers,
       response_status: response.status,
-      response_body: response_body
+      response_body: ActiveSupport::JSON.decode(response.body)
     )
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dictum
 version: !ruby/object:Gem::Version
-  version: 0.0.6.1
+  version: 0.0.7
 platform: ruby
 authors:
 - Alejandro Bezdjian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-07 00:00:00.000000000 Z
+date: 2017-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.3.3
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -90,20 +118,48 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.40'
+        version: '0.48'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: 0.48.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.40'
+        version: '0.48'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.48.0
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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.40.0
+        version: '0'
 description: Create automatic documentation of your API endpoints through your tests.
 email: alebezdjian@gmail.com
 executables: []
@@ -114,6 +170,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.md
 - README.md
@@ -153,7 +210,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Document your APIs.