betterdocs 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad6f53d72b6b1dc91c3464a277c97992814fcc8b34a55f1fd043ace97b58c27a
-  data.tar.gz: '0259b534dece36526365a0861d2750c5ac5c5446e24920ef4113f67d4f00103a'
+  metadata.gz: eaf01d4e2af6e80f36f2cd756ac230d7bb0f7eaa796ed0d65116839d75e74a65
+  data.tar.gz: 8582edc5843c2261b50b5d75db2574597ac6404bea1f62e01a98448c999d9e58
 SHA512:
-  metadata.gz: 8489c381f2cff832c4552f109f05c15fe092b95ea688025e98ef987ea4c714425dd981897b177ad6ad49d046c3166b20fb1cf10ac517a564373ca8080172fc89
-  data.tar.gz: a9858527e935a0ed22f82f218907a4010ad86a523de7504afa55890bc4dfed66a00347cec4f0ebe0aa7dd8587ec43cee441623bb874ae2686e86316a11725c06
+  metadata.gz: d3587cff52970a661523e4796c6cb38522388ddf64b2a1da9f3b519a512325c2133531c716b654497af64f76ff28c99ed574d61bba0a327d6032fbc79ee8a2d8
+  data.tar.gz: 36d4f09a69a6d5ae7fe326948ebed98e83c7528b76602dfa6beba7fbed70870ff6629c24f45587eea93bc0538fbb5bf49f9056c51d62f3502af5aa81635a29fd

data/VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

data/betterdocs.gemspec

@@ -1,18 +1,18 @@
 # -*- encoding: utf-8 -*-
-# stub: betterdocs 0.11.0 ruby lib
+# stub: betterdocs 0.12.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterdocs".freeze
-  s.version = "0.11.0"
+  s.version = "0.12.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["betterplace Developers".freeze]
-  s.date = "2022-12-07"
+  s.date = "2022-12-09"
   s.description = "This library provides tools to generate API documention for a web site's REST-ful JSON API.".freeze
   s.email = "developers@betterplace.org".freeze
-  s.extra_rdoc_files = ["README.md".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/version.rb".freeze]
-  s.files = [".codeclimate.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".semaphore/semaphore.yml".freeze, ".tool-versions".freeze, ".vscode/settings.json".freeze, "COPYING".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "betterdocs.gemspec".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/markdown/templates/README.md.erb".freeze, "lib/betterdocs/generator/markdown/templates/section.md.erb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/generator/swagger_static/index.html".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/tasks/doc.rake".freeze, "lib/betterdocs/version.rb".freeze, "spec/assets/app/assets/images/logos/logo.png".freeze, "spec/assets/app/controllers/api/foos_controller.rb".freeze, "spec/assets/app/views/api_v4/documentation/assets/CHANGELOG.md".freeze, "spec/assets/config/betterdocs.yml".freeze, "spec/betterdocs/dsl/controller/action/param_spec.rb".freeze, "spec/betterdocs/dsl/controller/action/response_spec.rb".freeze, "spec/betterdocs/dsl/json_type_mapper_spec.rb".freeze, "spec/betterdocs/dsl/result/collection_property_spec.rb".freeze, "spec/betterdocs/dsl/result/link_spec.rb".freeze, "spec/betterdocs/dsl/result/property_spec.rb".freeze, "spec/betterdocs/generator/markdown_spec.rb".freeze, "spec/betterdocs/global_spec.rb".freeze, "spec/betterdocs/json_params_representer_spec.rb".freeze, "spec/betterdocs/result_representer_spec.rb".freeze, "spec/betterdocs/sanitizer_spec.rb".freeze, "spec/controller_dsl_spec.rb".freeze, "spec/result_representer_dsl_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/responding.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/version.rb".freeze]
+  s.files = [".codeclimate.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".semaphore/semaphore.yml".freeze, ".tool-versions".freeze, ".vscode/settings.json".freeze, "COPYING".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "betterdocs.gemspec".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/markdown/templates/README.md.erb".freeze, "lib/betterdocs/generator/markdown/templates/section.md.erb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/generator/swagger_static/index.html".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/responding.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/tasks/doc.rake".freeze, "lib/betterdocs/version.rb".freeze, "spec/assets/app/assets/images/logos/logo.png".freeze, "spec/assets/app/controllers/api/foos_controller.rb".freeze, "spec/assets/app/views/api_v4/documentation/assets/CHANGELOG.md".freeze, "spec/assets/config/betterdocs.yml".freeze, "spec/betterdocs/dsl/controller/action/param_spec.rb".freeze, "spec/betterdocs/dsl/controller/action/response_spec.rb".freeze, "spec/betterdocs/dsl/json_type_mapper_spec.rb".freeze, "spec/betterdocs/dsl/result/collection_property_spec.rb".freeze, "spec/betterdocs/dsl/result/link_spec.rb".freeze, "spec/betterdocs/dsl/result/property_spec.rb".freeze, "spec/betterdocs/generator/markdown_spec.rb".freeze, "spec/betterdocs/global_spec.rb".freeze, "spec/betterdocs/json_params_representer_spec.rb".freeze, "spec/betterdocs/result_representer_spec.rb".freeze, "spec/betterdocs/sanitizer_spec.rb".freeze, "spec/controller_dsl_spec.rb".freeze, "spec/result_representer_dsl_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "https://github.com/betterplace/betterdocs".freeze
   s.rdoc_options = ["--title".freeze, "Betterdocs".freeze, "--main".freeze, "README.md".freeze]
   s.rubygems_version = "3.3.26".freeze

data/lib/betterdocs/dsl/controller/action/response.rb

@@ -17,8 +17,13 @@ class Betterdocs::Dsl::Controller::Action::Response
 
   def data
     @data ||= instance_eval(&@data_block)
-    if hash = @data.ask_and_send(:to_hash)
-      hash[:data].present? or raise Error, "result for #{controller}##{action} is empty"
+    @data.is_a? Betterdocs::Responding or
+      raise Error, "result #{@data.class} is not Betterdocs::Responding"
+    hash = @data.to_hash
+    if hash.key?(:data) && hash[:data].empty?
+      raise Error, "result data for action #{controller}##{action} is empty"
+    elsif hash.empty?
+      raise Error, "result for action #{controller}##{action} is empty"
     end
     @data
   rescue => e
@@ -48,7 +53,12 @@ class Betterdocs::Dsl::Controller::Action::Response
   end
 
   def to_json(*a)
+    data.nil? and raise Error, "result for action #{controller}##{action} was nil"
+    unless data.is_a?(Betterdocs::Responding)
+      infobar.puts "#{data.class}".red
+      infobar.puts "Result of type #{data.class} for action #{controller}##{action} is not hash / Betterdocs::Representer"
+    end
     my_data = data.ask_and_send(:to_hash) || data
-    my_data.to_json(*a)
+    data.to_json(*a)
   end
 end

data/lib/betterdocs/representer.rb

@@ -1,6 +1,8 @@
 require 'action_controller'
+require 'betterdocs/responding'
 
 module Betterdocs::Representer
+  include Betterdocs::Responding
   extend ActiveSupport::Concern
 
   def as_json(*)
@@ -9,6 +11,8 @@ module Betterdocs::Representer
     end.hashify(self)
   end
 
+  alias to_hash as_json
+
   def to_json(*a)
     JSON::generate(as_json, *a)
   end

data/lib/betterdocs/responding.rb

@@ -0,0 +1,7 @@
+# This module should be included in all objects used in an API response which
+# should implement a #to_hash method.
+module Betterdocs
+  module Responding
+    implement :to_hash, :submodule
+  end
+end

data/lib/betterdocs/version.rb

@@ -1,6 +1,6 @@
 module Betterdocs
   # Betterdocs version
-  VERSION         = '0.11.0'
+  VERSION         = '0.12.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/betterdocs.rb

@@ -14,8 +14,10 @@ module Betterdocs
 end
 
 require 'betterdocs/version'
+require 'betterdocs/responding'
 require 'betterdocs/dsl'
 require 'betterdocs/sanitizer'
+require 'betterdocs/representer'
 require 'betterdocs/result_representer'
 require 'betterdocs/result_representer_collector'
 require 'betterdocs/controller_collector'

data/spec/betterdocs/dsl/controller/action/response_spec.rb

@@ -18,7 +18,7 @@ describe Betterdocs::Dsl::Controller::Action::Response do
       'Result',
       representer: representer,
       to_hash: { data: %w[ fake-it ] }
-    )
+    ).extend Betterdocs::Responding
   end
 
   let :response do
@@ -41,10 +41,23 @@ describe Betterdocs::Dsl::Controller::Action::Response do
   end
 
   it 'complains about missing data in example responses' do
-    allow(result_data).to receive(:to_hash).and_return('data' => [])
+    allow(result_data).to receive(:to_hash).and_return(data: [])
     expect { response.data }.to raise_error(Betterdocs::Dsl::Controller::Action::Response::Error)
   end
 
+  context 'foo' do
+    let :result_data do
+      double
+    end
+
+    it "complains about data that isn't Betterdocs::Responding" do
+      expect { response.data }.to raise_error(
+        Betterdocs::Dsl::Controller::Action::Response::Error,
+        /is not Betterdocs::Responding/
+      )
+    end
+  end
+
   it 'has data' do
     expect(response.data).to eq result_data
   end

data/spec/betterdocs/json_params_representer_spec.rb

@@ -71,9 +71,4 @@ describe Betterdocs::JsonParamsRepresenter do
       expect(param.required).to eq true
     end
   end
-
-  it 'foos' do
-    puts docs.to_s
-    skip
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: betterdocs
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - betterplace Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-07 00:00:00.000000000 Z
+date: 2022-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -199,6 +199,7 @@ extra_rdoc_files:
 - lib/betterdocs/railtie.rb
 - lib/betterdocs/rake_tasks.rb
 - lib/betterdocs/representer.rb
+- lib/betterdocs/responding.rb
 - lib/betterdocs/result_representer.rb
 - lib/betterdocs/result_representer_collector.rb
 - lib/betterdocs/sanitizer.rb
@@ -251,6 +252,7 @@ files:
 - lib/betterdocs/railtie.rb
 - lib/betterdocs/rake_tasks.rb
 - lib/betterdocs/representer.rb
+- lib/betterdocs/responding.rb
 - lib/betterdocs/result_representer.rb
 - lib/betterdocs/result_representer_collector.rb
 - lib/betterdocs/sanitizer.rb