rspec-api-docs 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 366d34d11131e28d3d3c88024ae9ffce5d2d2f27
-  data.tar.gz: 6a143737560c1d8ac8630a35761da4ac45e1efab
+  metadata.gz: eee6ccdbceb3b61271298301b471e3d09a9b7edb
+  data.tar.gz: 8a1e3b753359755cde4ca89586ffd5f3163d3d4e
 SHA512:
-  metadata.gz: c144b0cb4b2e0684c141fa92fe5edba7492e2dcd8e28adfd7f02ce530326848efb0cb3179753d8e36e529b03af53742ebf2fec77cf36345d00ba3bb328ff8f82
-  data.tar.gz: 7eb7c7a1b0283bfacecde7db7069c116809e0adf6a1a48969549281716e370d4fd24bcff1898717124fdf03d319ce0b904c6fa7a0aecf24ab99a887fa500d109
+  metadata.gz: 97555c1200f96e8370b333fc9ff86e5ffb011a782fa51aab4231d74527d1e0d21484bad7326233b7248c3cedb816fc29e1fdc91d851704810ea2a07216e2c98c
+  data.tar.gz: 6f93f8c19a225543f023a737e52a0ac8c6829c7fd62d97ed8f62b8c3e21d5697599e7594f73f41e51e3d5b8be6e15bad7ed1f57ef6be23899577b81fedb44cc5

data/README.md

@@ -154,6 +154,12 @@ Accepts a string that describes the resource.
 
 > Characters inhabit the Land of Ooo.
 
+#### `resource_precedence`
+
+Accepts an optional integer.
+
+Lower numbers are ordered first.
+
 #### `name`
 
 Accepts a string of the name of the resource.
@@ -185,20 +191,24 @@ Note: This defaults to the path of the first route requested in the example.
 
 #### `field`
 
-Accepts a `name`, `description`, and optionally a `scope` and `type`.
+Accepts a `name`, `description`, and optionally a `scope`, `type`, and `example`.
 
 - `name` [`Symbol`] the name of the response field
 - `description` [`String`] a description of the response field
 - `scope` [`Symbol`, `Array<Symbol>`] _(optional)_ how the field is scoped
 - `type` [`String`] _(optional)_ the type of the returned field
+- `example` _(optional)_ an example value
 
 This can be called multiple times for each response field.
 
 ``` ruby
-field :id, 'The id of a character', scope: :character, type: 'integer'
+field :id, 'The id of a character', scope: :character, type: 'integer', example: 42
 field :name, "The character's name", scope: :character, type: 'string'
 ```
 
+The `example` is useful if the data might change (i.e. a database ID column).
+The value will be substituted in the resulting JSON.
+
 #### `param`
 
 Accepts a `name`, `description`, and optionally a `scope`, `type`, and `required` flag.
@@ -228,6 +238,12 @@ note 'You need to supply an id!'
 note :warning, "An error will be thrown if you don't supply an id!"
 ```
 
+#### `precedence`
+
+Accepts an optional integer.
+
+Lower numbers are ordered first.
+
 See the integration specs for more examples of the DSL in use.
 
 ### Formatter
@@ -255,6 +271,34 @@ end
 
 See [the documentation](http://www.rubydoc.info/github/twe4ked/rspec-api-docs/master).
 
+## Rake tasks
+
+``` ruby
+require 'rspec_api_docs/rake_task'
+
+RspecApiDocs::Rake.new do |task| # docs:generate
+  # Pattern for where to find the specs
+  task.pattern = 'spec/requests/**/*_spec.rb'
+
+  # Extra RSpec options
+  task.rspec_opts = ['--format progress']
+end
+
+RspecApiDocs::Rake.new do |task| # docs:ensure_updated
+  # Same as options above with some extras for when verify is true
+
+  # Raise an error if the generated docs don't match the existing docs
+  # The verify option only works with the :json renderer.
+  task.verify = true
+
+  # The existing (committed) output file
+  task.existing_file = 'docs/index.json'
+end
+
+# Non-verify task with custom name
+RspecApiDocs::Rake.new :custom_task_name
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
@@ -271,11 +315,6 @@ Regenerate this project's integration spec docs locally:
 $ ./bin/generate_integration_docs
 ```
 
-## TODO
-
-- Allow specifying an order (`precedence`?)
-- Order Resources and Examples alphabetically
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/Rakefile

@@ -24,6 +24,15 @@ RspecApiDocs::RakeTask.new do |task|
   ]
   task.pattern = 'spec/integration/rspec_api_docs_spec.rb'
   task.existing_file = 'spec/integration/output/json/index.json'
+  task.verify = true
+end
+
+RspecApiDocs::RakeTask.new do |task|
+  task.verbose = false
+  task.rspec_opts = [
+    '--format progress',
+  ]
+  task.pattern = 'spec/integration/rspec_api_docs_spec.rb'
 end
 
 task default: [:rspec, :rubocop, :generate_integration_docs]

data/lib/rspec_api_docs/after.rb

@@ -1,3 +1,5 @@
+# TODO: Move Resource out of formatter dir
+require 'rspec_api_docs/formatter/resource'
 require 'rspec_api_docs/after/type_checker'
 
 module RspecApiDocs
@@ -15,8 +17,11 @@ module RspecApiDocs
 
       metadata[:requests].each do |request, response|
         request.params.each do |key, value|
-          if metadata[:parameters] && metadata[:parameters].has_key?(key.to_sym)
-            After::TypeChecker.call(type: metadata[:parameters][key.to_sym][:type], value: value)
+          parameter = RspecApiDocs::Resource::Example.new(example).parameters
+            .select { |parameter| parameter.name == key.to_sym }.first
+
+          if parameter
+            After::TypeChecker.call(type: parameter.type, value: value)
           else
             raise UndocumentedParameter, "undocumented parameter included in request #{key.inspect}"
           end

data/lib/rspec_api_docs/dsl/doc_proxy.rb

@@ -36,6 +36,15 @@ module RspecApiDocs
         metadata[METADATA_NAMESPACE][:resource_description] = value
       end
 
+      # For setting the precedence of the resource
+      #
+      # Lower numbers will be ordered higher
+      #
+      # @param value [Integer] the precedence
+      def resource_precedence(value)
+        metadata[METADATA_NAMESPACE][:resource_precedence] = value
+      end
+
       # For setting a description of the example.
       #
       # E.g. "Allows you to return a single character."
@@ -76,13 +85,15 @@ module RspecApiDocs
       # @param description [String] a description of the response field
       # @param scope [Symbol, Array<Symbol>] how the field is scoped
       # @param type [String]
+      # @param example an example value
       # @return [void]
-      def field(name, description, scope: [], type: nil)
+      def field(name, description, scope: [], type: nil, example: nil)
         metadata[METADATA_NAMESPACE][:fields] ||= {}
-        metadata[METADATA_NAMESPACE][:fields][name] = {
+        metadata[METADATA_NAMESPACE][:fields][{name: name, scope: scope}] = {
           description: description,
           scope: Array(scope),
           type: type,
+          example: example,
         }
       end
 
@@ -107,7 +118,7 @@ module RspecApiDocs
       # @return [void]
       def param(name, description, scope: [], type: nil, required: false)
         metadata[METADATA_NAMESPACE][:parameters] ||= {}
-        metadata[METADATA_NAMESPACE][:parameters][name] = {
+        metadata[METADATA_NAMESPACE][:parameters][{name: name, scope: scope}] = {
           description: description,
           scope: Array(scope),
           type: type,
@@ -126,6 +137,15 @@ module RspecApiDocs
         metadata[METADATA_NAMESPACE][:note] ||= {}
         metadata[METADATA_NAMESPACE][:note][level] = value
       end
+
+      # For setting the precedence of an example
+      #
+      # Lower numbers will be ordered higher
+      #
+      # @param value [Integer] the precedence
+      def precedence(value)
+        metadata[METADATA_NAMESPACE][:example_precedence] = value
+      end
     end
   end
 end

data/lib/rspec_api_docs/formatter.rb

@@ -40,7 +40,7 @@ module RspecApiDocs
     #
     # @return [void]
     def close(null_notification)
-      renderer.new(resources.values.sort_by(&:name)).render
+      renderer.new(resources.values.sort_by { |resource| [resource.precedence, resource.name].join }).render
     end
 
     private

data/lib/rspec_api_docs/formatter/resource.rb

@@ -33,7 +33,7 @@ module RspecApiDocs
     #
     # @return [Array<Example>]
     def examples
-      @examples.sort_by(&:name)
+      @examples.sort_by { |example| [example.precedence, example.name].join }
     end
 
     # Add an example
@@ -43,6 +43,15 @@ module RspecApiDocs
       @examples << example
     end
 
+    # @return [String, nil]
+    def precedence
+      metadata[:resource_precedence]
+    end
+
+    def inspect
+      "#<RspecApiDocs::Resource #{name.inspect}, @examples=#{examples.inspect}>"
+    end
+
     private
 
     def metadata

data/lib/rspec_api_docs/formatter/resource/example.rb

@@ -1,4 +1,5 @@
 require 'rspec_api_docs/formatter/resource/example/request_headers'
+require 'rspec_api_docs/formatter/resource/example/deep_hash_set'
 
 module RspecApiDocs
   class Resource
@@ -31,8 +32,8 @@ module RspecApiDocs
       #
       # @return [Array<Parameter>]
       def parameters
-        metadata.fetch(:parameters, []).map do |name, parameter|
-          Parameter.new(name, parameter)
+        metadata.fetch(:parameters, []).map do |name_hash, parameter|
+          Parameter.new(name_hash[:name], parameter)
         end
       end
 
@@ -40,8 +41,8 @@ module RspecApiDocs
       #
       # @return [Array<ResponseField>]
       def response_fields
-        metadata.fetch(:fields, []).map do |name, field|
-          ResponseField.new(name, field)
+        metadata.fetch(:fields, []).map do |name_hash, field|
+          ResponseField.new(name_hash[:name], field)
         end
       end
 
@@ -89,6 +90,15 @@ module RspecApiDocs
         metadata.fetch(:note, {})
       end
 
+      # @return [String, nil]
+      def precedence
+        metadata[:example_precedence]
+      end
+
+      def inspect
+        "#<RspecApiDocs::Resource::Example #{name.inspect}>"
+      end
+
       private
 
       def request_response_pairs
@@ -111,7 +121,15 @@ module RspecApiDocs
       end
 
       def response_body(body)
-        body.empty? ? nil : body
+        unless body.empty?
+          parsed_body = JSON.parse(body, symbolize_names: true)
+          response_fields.each do |f|
+            unless f.example.nil?
+              DeepHashSet.call(parsed_body, f.scope + [f.name], f.example)
+            end
+          end
+          JSON.dump(parsed_body)
+        end
       end
 
       def response_status_text(status)

data/lib/rspec_api_docs/formatter/resource/example/deep_hash_set.rb

@@ -0,0 +1,58 @@
+module RspecApiDocs
+  class Resource
+    class Example
+      class DeepHashSet
+        attr_reader :hash, :keys, :value, :node
+
+        def self.call(*args)
+          new(*args).call
+        end
+
+        def initialize(hash, keys, value)
+          @hash = hash
+          @keys = keys
+          @value = value
+          @node = []
+        end
+
+        def call
+          keys.each_with_index do |key, index|
+            case
+            when key.empty? # TODO: should this require `key == []`?
+              deep_set_value_at_array(index)
+              break
+            when index == keys.size - 1
+              set_value_at(key)
+            else
+              node << key
+            end
+          end
+
+          hash
+        end
+
+        private
+
+        attr_reader :node
+
+        def deep_set_value_at_array(index)
+          array = deep_find(hash, node)
+          array && array.each do |inner_hash|
+            DeepHashSet.call(inner_hash, keys[index+1..-1], value)
+          end
+        end
+
+        def set_value_at(key)
+          part = deep_find(hash, node)
+          if part.is_a?(Hash) && !part[key].nil?
+            part[key] = value
+          end
+        end
+
+        def deep_find(hash, keys)
+          keys.inject(hash) { |h, k| h && h[k] }
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/resource/parameter.rb

@@ -34,6 +34,11 @@ module RspecApiDocs
         name == other.name &&
           parameter == other.parameter
       end
+
+      # @return [String, nil]
+      def type
+        parameter[:type]
+      end
     end
   end
 end

data/lib/rspec_api_docs/formatter/resource/response_field.rb

@@ -29,6 +29,11 @@ module RspecApiDocs
         field[:description]
       end
 
+      # Example value
+      def example
+        field[:example]
+      end
+
       # @return [true, false]
       def ==(other)
         name == other.name &&

data/lib/rspec_api_docs/rake_task.rb

@@ -10,23 +10,23 @@ module RspecApiDocs
       extend RSpec::Matchers
     end
 
-    attr_reader :name
-
     attr_accessor \
       :verbose,
       :pattern,
       :rspec_opts,
       :existing_file,
-      :dir
+      :dir,
+      :verify
 
     def initialize(name = nil, &block)
-      @name = name || :'docs:ensure_updated'
+      @name = name
       @verbose = true
       @pattern = 'spec/requests/**/*_spec.rb'
       @rspec_opts = []
       @existing_file = 'docs/index.json'
+      @verify = false
 
-      block.call(self)
+      block.call(self) if block
 
       define
     end
@@ -34,17 +34,13 @@ module RspecApiDocs
     private
 
     def define
-      desc 'Ensure API docs are up to date'
+      desc default_desc
       task name do
-        @dir = Dir.mktmpdir
+        @dir = Dir.mktmpdir if verify
 
         rspec_task.run_task(verbose)
 
-        configure_rspec
-
-        RSpecMatchers.expect(generated).to RSpecMatchers.eq(existing)
-
-        remove_dir
+        verify! if verify
       end
     end
 
@@ -59,11 +55,7 @@ module RspecApiDocs
     def rspec_task
       RSpec::Core::RakeTask.new.tap do |task|
         task.pattern = pattern
-        task.rspec_opts = rspec_opts + [
-          '--format RspecApiDocs::Formatter',
-          '--order defined',
-          "--require #{spec_helper.path}",
-        ]
+        task.rspec_opts = task_rspec_opts
       end
     end
 
@@ -87,5 +79,31 @@ module RspecApiDocs
     def remove_dir
       FileUtils.remove_entry dir
     end
+
+    def verify!
+      configure_rspec
+
+      RSpecMatchers.expect(generated).to RSpecMatchers.eq(existing)
+
+      remove_dir
+    end
+
+    def task_rspec_opts
+      arr = rspec_opts + [
+        '--format RspecApiDocs::Formatter',
+        '--order defined',
+      ]
+      arr += ["--require #{spec_helper.path}"] if verify
+      arr
+    end
+
+    def name
+      @name ||
+        verify ? :'docs:ensure_updated' : :'docs:generate'
+    end
+
+    def default_desc
+      verify ? 'Ensure API docs are up to date' : 'Generate API docs'
+    end
   end
 end

data/lib/rspec_api_docs/version.rb

@@ -1,3 +1,3 @@
 module RspecApiDocs
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-api-docs
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Odin Dutton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-05 00:00:00.000000000 Z
+date: 2017-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -149,6 +149,7 @@ files:
 - lib/rspec_api_docs/formatter/renderer/slate_renderer/slate_index.html.md.erb
 - lib/rspec_api_docs/formatter/resource.rb
 - lib/rspec_api_docs/formatter/resource/example.rb
+- lib/rspec_api_docs/formatter/resource/example/deep_hash_set.rb
 - lib/rspec_api_docs/formatter/resource/example/request_headers.rb
 - lib/rspec_api_docs/formatter/resource/parameter.rb
 - lib/rspec_api_docs/formatter/resource/response_field.rb