reqres_rspec 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37c81ea83e40e5956d5ac04dc91e70b7c82c71a4
-  data.tar.gz: 426569056ed69c40110d35968089b7bd23ecea7f
+  metadata.gz: c6aa9c6c95beaf16c80ee51d0578c483c385683f
+  data.tar.gz: 1906b7f8701dc21badcbfc7c0353ef506a289dec
 SHA512:
-  metadata.gz: 0b4ddf6150b33d84f1a9a5be2bdc77a4a8471b5d8ea2ecd6d63b8ad1aafe0f86f0cc8a07b9760fad195e57f00dfdb1c7ad7a40994eeb79f45493de2f31833cc2
-  data.tar.gz: 2ed8b1bb73d1f205d90612770a494d8fd5f463be54c4aa2000df89baa40400b8f8836def7cfa45c1d9ceeb7d778cd761fd1dc19a5cae3c0aaa2f7e177d38d79d
+  metadata.gz: ff896169c1336ae45ec127cd22e8c7df6d25c837a3d1781efba46572209a12af74c23da1fd635ce5fa1fd3b88dd5e0e4148aac85fe48912e6d83f03d8021ceaf
+  data.tar.gz: 8ed9a4b7f53867fd4ec4e1d9b199843ce01f7ece0ac864214ab5c569e502706db1e37afc6f1e532c8e53e22c245a99238e51c20f1a886a823803601e747c3f9f

data/README.md

@@ -1,28 +1,26 @@
 # ReqresRspec
 
-Gem generates API documentation from your integration tests written with `rspec`. No additional DSL needed. Beside covering rspec tests, documentation may be extended with API controller action comments win `yardoc` style. Documentation is generated in JSON, YAML, HTML, PDF formats.
+Gem generates API documentation from your integration tests written with `rspec`.
+
+No additional DSL needed. Beside covering rspec tests, documentation may be extended with API controller action comments in `yardoc` style.
+
+Documentation is generated in JSON, YAML, HTML, PDF formats.
 
 ## Installation
 
-### Gem
+### 1) Gem
 
-Add this line to your application's Gemfile:
+Just add this gem to `Gemfile` of your API Application
 
-    gem 'reqres_rspec'
+    gem 'reqres_rspec', group: :test
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install reqres_rspec
+### 2) PDF generator
 
-### PDF generator
-
-Install `prince` http://www.princexml.com/download/
-
-For MacOS this will be
+Install `prince` http://www.princexml.com/download/ . For MacOS installation commands are
 
 ```
 wget http://www.princexml.com/download/prince-9.0r2-macosx.tar.gz
@@ -33,17 +31,75 @@ cd prince-9.0r2-macosx
 
 ## Usage
 
+by default `reqres_rspec` is not active (this may be configured!). To activate it, run `rspec` with
+
+`REQRES_RSPEC=1 bundle exec rspec`
+
+Documentation will be put into your application's `/doc` folder
+
 ### Sample controller action
 
-TODO: Write usage instructions here
+```ruby
+  # @description creates Category from given parameters
+  # description text may be multiline
+  # @params category[title] required String Category title
+  # @params category[weight] in which order Category will be shown
+  # param text may also be multiline
+  def create
+    category = Category.new(create_category_params)
+
+    if category.save
+      render json: { category: category }.to_json, status: 201
+    else
+      render json: { errors: category.errors.full_messages }, status: 422
+    end
+  end
+```
+
+Description param text is started with `@description` and may be multiline.
+Each param text is started with `@params` and first word will be param name, then optionally `required`, then optionally type (`Integer`, `String` etc), and finally param description, which may be multiline as well.
 
 ### Sample rspec test
 
-TODO: Write usage instructions here
+```ruby
+  describe 'Create' do
+    it 'creates category' do
+      post :create, category: { name: 'Cookies' }
+      ...
+    end
+
+    it 'some other example', collect_for_doc: false do
+      ...
+    end
+  end
+```
+
+ By default all examples will be added to docs. Example may be excluded from docs with option `collect_for_doc: false`
+
+ Doc will use full example description, as a title for each separate spec
 
 ### Generates documentation example
 
-TODO: Write usage instructions here
+[![Generated Doc](http://i44.tinypic.com/kda1pw.png)](http://i44.tinypic.com/kda1pw.png)
+[![Generated Doc](http://i39.tinypic.com/2w3p6vl.png)](http://i39.tinypic.com/2w3p6vl.png)
+
+Documentation is written in HTML format, which then converted to PDF. PDF files are textual, support search and have internal navigation links
+
+## Configuration
+
+TODO: Write instruction on gem configuration
+
+## Future plans
+
+1) Write documentation in YAML, JSON formats
+
+2) Add configuration (folders with API specs, default generate spec for all examples, or opt-in generation)
+
+3) Cover with tests
+
+4) Remove dependency on `rails`
+
+5) Add demo for `Rails`, `Rails API`, `Sinatra`
 
 ## Contributing
 

data/Rakefile

@@ -1 +1 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'

data/lib/reqres_rspec.rb

@@ -10,9 +10,12 @@ if defined?(RSpec) && ENV['REQRES_RSPEC'] == '1'
     config.after(:each) do
       # TODO: remove boilerplate code
       # TODO: better options
-      unless self.example.options.has_key?(:collect_for_doc) && !self.example.options[:collect_for_doc]
-        if defined?(self.request) && defined?(self.response)
-          collector.collect(self, self.request, self.response)
+      meta_data = self.class.example.metadata
+      if meta_data[:type] == :request
+        begin
+          collector.collect(self, self.request, self.response) unless meta_data[:skip_reqres] == true
+        rescue NameError
+          raise $!
         end
       end
     end

data/lib/reqres_rspec/collector.rb

@@ -50,9 +50,17 @@ module ReqresRspec
         end
       end
 
+      ex_gr = spec.class.example.metadata[:example_group]
+      section = ex_gr[:description]
+      while !ex_gr.nil? do
+        section = ex_gr[:description]
+        ex_gr = ex_gr[:parent_example_group]
+      end
+
       self.records << {
-        title: spec.example.full_description,
-        description: description,
+        group: section, # Top level example group
+        title: spec.class.example.full_description,
+        description: spec.class.description,
         params: params,
         request_path: get_symbolized_path(request),
         request: {
@@ -155,8 +163,10 @@ module ReqresRspec
 
         comment_lines.reverse
       else
-        'not found'
+        ['not found']
       end
+    rescue Errno::ENOENT
+      ['not found']
     end
 
     # returns description action comments
@@ -217,4 +227,4 @@ module ReqresRspec
       params
     end
   end
-end
+end

data/lib/reqres_rspec/version.rb

@@ -1,3 +1,3 @@
 module ReqresRspec
-  VERSION = '0.0.15'
+  VERSION = '0.0.16'
 end

data/lib/reqres_rspec/writers/html.rb

@@ -1,3 +1,5 @@
+require 'coderay'
+
 module ReqresRspec
   module Writers
     class Html
@@ -10,6 +12,9 @@ module ReqresRspec
         cleanup
         generate_header
         generate_specs
+
+        append_index
+        append_panel
       end
 
       private
@@ -27,6 +32,8 @@ module ReqresRspec
       # TODO: more info
       def cleanup
         FileUtils.rm_rf(Dir.glob("#{Rails.root}/doc/rspec_doc_*.html"), secure: true)
+        FileUtils.rm_rf(Dir.glob("#{Rails.root}/doc/index.html"), secure: true)
+        FileUtils.rm_rf(Dir.glob("#{Rails.root}/doc/panel.html"), secure: true)
       end
 
       # generates contents of HTML docs
@@ -53,13 +60,32 @@ module ReqresRspec
 
           rendered_doc = ERB.new(File.open(tpl_path).read).result(binding)
 
-          path = File.join(Rails.root, 'doc', "rspec_doc_#{('0000' + (@index).to_s)[-5, 5]}.html")
+          path = File.join(Rails.root, 'doc', "rspec_doc_#{@index.to_s.rjust(5, '0') }.html")
           file = File.open(path, 'w')
           file.write(rendered_doc)
           file.close
           puts "Reqres::Writers::Html saved doc spec to #{path}"
         end
       end
+
+      # creates an index file with iframes if does not exists
+      def append_index
+        index_file = File.join(Rails.root, 'doc', 'index.html')
+        unless File.exists?(index_file)
+          tpl_path = File.join(File.dirname(__FILE__), 'templates', 'index.erb')
+          rendered_doc = ERB.new(File.open(tpl_path).read).result(binding)
+          File.write index_file, rendered_doc
+        end
+      end
+
+      def append_panel
+        index_file = File.join(Rails.root, 'doc', 'panel.html')
+        unless File.exists?(index_file)
+          tpl_path = File.join(File.dirname(__FILE__), 'templates', 'panel.erb')
+          rendered_doc = ERB.new(File.open(tpl_path).read).result(binding)
+          File.write index_file, rendered_doc
+        end
+      end
     end
   end
-end
+end

data/lib/reqres_rspec/writers/templates/header.erb

@@ -10,7 +10,7 @@
       color: #333333;
       font-family: 'Verdana', 'Droid Sans', sans-serif;
       font-size: 14px;
-      padding: 0;
+      padding: 15px;
       margin: 0;
     }
     body *{

data/lib/reqres_rspec/writers/templates/index.erb

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= Rails.application.class.to_s.sub('::Application', '') %> API Documentation</title>
+    <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
+    <link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'>
+    <link href='http://fonts.googleapis.com/css?family=Droid+Sans+Mono' rel='stylesheet' type='text/css'>
+    <style type="text/css">
+      body {
+        margin:0;
+        padding:0;
+        border:0;
+        width:100%;
+        background:#fff;
+        min-width:600px;
+        font-size:90%;
+      }
+    </style>
+  </head>
+  <frameset cols="350,*" frameborder="1" border="1" bordercolor="#999999" framespacing="1">
+    <frame name="panel" src="./panel.html">
+    <frame name="specs" src="./rspec_doc_00000.html">
+  </frameset>
+</html>

data/lib/reqres_rspec/writers/templates/panel.erb

@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= Rails.application.class.to_s.sub('::Application', '') %> API Documentation</title>
+    <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
+    <link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'>
+    <link href='http://fonts.googleapis.com/css?family=Droid+Sans+Mono' rel='stylesheet' type='text/css'>
+    <style type="text/css">
+      body {
+        color: #333333;
+        font-family: 'Verdana', 'Droid Sans', sans-serif;
+        font-size: 12px;
+        padding: 0;
+        margin: 0;
+      }
+      body *{
+        -webkit-box-sizing: border-box;
+        -moz-box-sizing: border-box;
+        box-sizing: border-box;
+      }
+      h1, h2, h3 {
+        padding: 10px 5px;
+        margin: 0;
+        background: #dedede;
+      }
+      h1 {
+        font-size: 1.5em;
+      }
+      h2 {
+        font-size: 1.3em;
+        padding-bottom:5px;
+      }
+      h3 {
+        font-size: 0.95em;
+        padding-bottom:0px;
+      }
+      ul, ul li {
+        list-style-type: none;
+        padding:0px;
+        margin:0px;
+      }
+      ul li {
+        border-bottom:1px solid lightgray;
+        background: #fefefe;
+      }
+      ul li:first-child {
+        border-top:1px solid lightgray;
+      }
+      ul li:nth-child(2n+1) {
+        background: #eeeeee;
+      }
+      ul li a {
+        padding:5px;
+        display: block;
+      }
+      ul li a:hover {
+        background: #dedede;
+      }
+      a {
+        color: #1d96d2;
+        text-decoration: none;
+      }
+      span.method {
+        border-radius: 3px;
+        background-color: darkgray;
+        color: white;
+        padding: 3px;
+        font-size: 90%;
+        width: 56px;
+        display: inline-block;
+        text-align: center;
+      }
+      span.method.get {
+        background-color: darkgreen;
+      }
+      span.method.post {
+        background-color: darkorange;
+      }
+      span.method.put, span.method.patch {
+        background-color: darkorange;
+      }
+      span.method.delete {
+        background-color: darkred;
+      }
+    </style>
+  </head>
+  <body>
+    <h1><a href="rspec_doc_00000.html" target="specs">
+      <%= Rails.application.class.to_s.sub('::Application', '') %> API
+    </a></h1>
+    <% @records.group_by{|h| h[:group]}.each do |group, items| %>
+      <h2><%= group %></h2>
+      <% items.group_by{|h| h[:request_path]}.each do |path, records| %>
+        <h3><%= path %></h3>
+        <ul>
+          <% records.each_with_index do |record, index| %>
+            <li>
+              <a href="rspec_doc_<%= (index + 1).to_s.rjust(5, '0') %>.html" target="specs">
+                <span class="method <%= record[:request][:method].downcase %>"><%= record[:request][:method] %></span>
+                <%= record[:description] %><br />
+              </a>
+            </li>
+          <% end %>
+        </ul>
+      <% end %>
+    <% end %>
+  </body>
+</html>

data/lib/reqres_rspec/writers/templates/spec.erb

@@ -10,7 +10,7 @@
       color: #333333;
       font-family: 'Verdana', 'Droid Sans', sans-serif;
       font-size: 14px;
-      padding: 0;
+      padding: 15px;
       margin: 0;
     }
     body *{
@@ -66,7 +66,7 @@
       border-radius: 4px;
       overflow: hidden;
     }
-    table{
+    table.params{
       width: 100%;
       font-size: 1em;
       padding: 0;
@@ -74,29 +74,29 @@
       border-collapse: collapse;
       border-spacing: 0px;
     }
-    tr{
+    table.params tr{
       border-top: 1px solid #cccccc;
     }
-    tr:first-child{
+    table.params tr:first-child{
       border-top: 0
     }
-    th, td{
+    table.params th, td{
       margin: 0;
       padding: 5px 8px;
       text-align: left;
       border-left: 1px solid #cccccc;
       font-size: 1em;
     }
-    th:first-child, td:first-child{
+    table.params th:first-child, td:first-child{
       border-left: 0;
     }
-    td{
+    table.params td{
       background: #f9f9f9;
     }
-    tr:nth-child(2n+1) td{
+    table.params tr:nth-child(2n+1) td{
       background: #ffffff;
     }
-    td i{
+    table.params td i{
       font-style: normal;
       font-weight: 300;
       float: right;
@@ -122,6 +122,12 @@
       font-weight: 400;
       font-style: normal;
     }
+    .CodeRay td {
+      width: 99%;
+    }
+    .CodeRay td.line-numbers {
+      width: 1%;
+    }
     ol{
       margin: 0 0 10px 0;
       padding: 0 10px 0 50px;
@@ -155,7 +161,7 @@
     <% if @record[:params].size > 0 %>
       <h5>Parameters</h5>
       <div class="table">
-        <table>
+        <table class="params">
           <tr>
             <th>Name</th>
             <th>Type</th>
@@ -183,7 +189,7 @@
     <code><%= @record[:request][:method] %> <%= @record[:request][:path] %></code>
 
     <h5>Query parameters</h5>
-    <code><%= @record[:request][:query_parameters] %></code>
+    <code><%= @record[:request][:query_parameters] if @record[:request][:method] == 'GET' %></code>
 
     <h5><a href="http://curl.haxx.se/docs/manpage.html">CURL</a> Example</h5>
     <code>TODO</code>
@@ -192,7 +198,7 @@
       <h5>Body</h5>
       <ol>
         <% @record[:request][:body].split("\n").each do |line| %>
-          <li><%= line %></li>
+          <li style="word-break:&;"><%= line %></li>
         <% end %>
       </ol>
     <% end %>
@@ -209,21 +215,18 @@
 
     <% if @record[:response][:body].present? %>
       <h5>Body</h5>
-      <ol>
-        <% lines = begin
-                     JSON.pretty_generate(
-                       JSON.parse(
-                         @record[:response][:body]
-                       )
+      <% lines = begin
+                   JSON.pretty_generate(
+                     JSON.parse(
+                       @record[:response][:body]
                      )
-                   rescue
-                     @record[:response][:body]
-                   end
-
-           lines.split("\n").each do |line| %>
-          <li><%= line %></li>
-        <% end %>
-      </ol>
+                   )
+                 rescue
+                   @record[:response][:body]
+                 end %>
+      <code>
+        <%= CodeRay.scan(lines, :json).div(line_numbers: :table) %>
+      </code>
     <% end %>
   </div>
 </body>

data/reqres_rspec.gemspec

@@ -4,20 +4,22 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'reqres_rspec/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "reqres_rspec"
+  spec.name          = 'reqres_rspec'
   spec.version       = ReqresRspec::VERSION
-  spec.authors       = ["rilian"]
-  spec.email         = ["dmitriyis@gmail.com"]
+  spec.authors       = ['rilian']
+  spec.email         = ['dmitriyis@gmail.com']
   spec.description   = %q{Generates API documentation in PDF, HTML, JSON, YAML format for integration tests written with RSpec}
   spec.summary       = %q{Generates API documentation in PDF, HTML, JSON, YAML format for integration tests written with RSpec}
-  spec.homepage      = "https://github.com/reqres-api/reqres_rspec"
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/reqres-api/reqres_rspec'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
+  spec.add_dependency 'coderay'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
 end

metadata

@@ -1,41 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: reqres_rspec
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - rilian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-18 00:00:00.000000000 Z
+date: 2014-06-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: coderay
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   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'
 description: Generates API documentation in PDF, HTML, JSON, YAML format for integration
@@ -46,7 +60,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -57,6 +71,8 @@ files:
 - lib/reqres_rspec/version.rb
 - lib/reqres_rspec/writers/html.rb
 - lib/reqres_rspec/writers/templates/header.erb
+- lib/reqres_rspec/writers/templates/index.erb
+- lib/reqres_rspec/writers/templates/panel.erb
 - lib/reqres_rspec/writers/templates/spec.erb
 - reqres_rspec.gemspec
 homepage: https://github.com/reqres-api/reqres_rspec
@@ -69,17 +85,17 @@ 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.0.6
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Generates API documentation in PDF, HTML, JSON, YAML format for integration