betterdocs 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43905ca43e64e65668831fed2e7c0d2eb1e0380347948c1d6f1aa7aa77bd8ea7
-  data.tar.gz: 6c52dcacf3ca65b2111f5e1da6655af8ab728c20e552ee90ca953e547c490699
+  metadata.gz: eaf01d4e2af6e80f36f2cd756ac230d7bb0f7eaa796ed0d65116839d75e74a65
+  data.tar.gz: 8582edc5843c2261b50b5d75db2574597ac6404bea1f62e01a98448c999d9e58
 SHA512:
-  metadata.gz: 493b9879a9c2bdcb1fd4d8858c59d34cf0a83eece18d15f1c7f005e84e57a127c101945c760cf0362d123b90006ecdcf2445a08cce586bd42cb882f4438d7df6
-  data.tar.gz: 4de261093b3b6b0cb4541d99e4d572cb239f41ca9091fbb41b9a2fc6df5be4e33d5a499ded80a19ac0f4bb740cb8709297ae145ee01a407c4ed8166c9ccebc47
+  metadata.gz: d3587cff52970a661523e4796c6cb38522388ddf64b2a1da9f3b519a512325c2133531c716b654497af64f76ff28c99ed574d61bba0a327d6032fbc79ee8a2d8
+  data.tar.gz: 36d4f09a69a6d5ae7fe326948ebed98e83c7528b76602dfa6beba7fbed70870ff6629c24f45587eea93bc0538fbb5bf49f9056c51d62f3502af5aa81635a29fd

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 3.1.2
+ruby 3.1.3
 bundler 2.3.17

data/README.md

@@ -22,6 +22,8 @@ This api generator requires that you follow the [representer pattern](http://nic
 
 ## Controller
 
+betterdocs comes with a DSL for the (Rails) controllers - see examples below.
+
 ```ruby
 class ThingsController < ApplicationController
   # :nocov: Documentation
@@ -99,6 +101,7 @@ module ThingsRepresenter
     example     'my_name'
   end
 
+  # Add a link to the links list in the resulting JSON.
   link :self do
     description to <<-end
       Link to this resource itself
@@ -109,6 +112,12 @@ module ThingsRepresenter
 end
 ```
 
+GENERATING
+----------
+
+`rake doc:api:push` will push the documentation onto a git branch.
+`rake doc:api:swagger` will call Swagger.
+
 RELEASING
 ---------
 

data/VERSION

@@ -1 +1 @@
-0.10.0
+0.12.0

data/betterdocs.gemspec

@@ -1,21 +1,21 @@
 # -*- encoding: utf-8 -*-
-# stub: betterdocs 0.10.0 ruby lib
+# stub: betterdocs 0.12.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterdocs".freeze
-  s.version = "0.10.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-08-16"
+  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.19".freeze
+  s.rubygems_version = "3.3.26".freeze
   s.summary = "Betterplace API documentation library".freeze
   s.test_files = ["spec/assets/app/controllers/api/foos_controller.rb".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]
 

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

@@ -17,8 +17,17 @@ class Betterdocs::Dsl::Controller::Action::Response
 
   def data
     @data ||= instance_eval(&@data_block)
+    @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
-    error = Error.new("#{e.class}: #{e}")
+    error = e.is_a?(Error) ? e : Error.new("#{e.class}: #{e}")
     error.set_backtrace e.backtrace.grep(/^#{Betterdocs.rails.root}/)
     raise error
   end
@@ -44,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.10.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

@@ -17,15 +17,18 @@ describe Betterdocs::Dsl::Controller::Action::Response do
     double(
       'Result',
       representer: representer,
-      to_json: '{ "the": "result" }'
-    )
+      to_hash: { data: %w[ fake-it ] }
+    ).extend Betterdocs::Responding
   end
 
   let :response do
     data = result_data
-    described_class.new do
+    object = described_class.new do
       data
     end
+    allow(object).to receive(:controller).and_return('TheController')
+    allow(object).to receive(:action).and_return('in_action')
+    object
   end
 
   let :param_value do
@@ -37,6 +40,24 @@ describe Betterdocs::Dsl::Controller::Action::Response do
     expect(response.params[:test]).to eq 'foo'
   end
 
+  it 'complains about missing data in example responses' do
+    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
@@ -54,6 +75,6 @@ describe Betterdocs::Dsl::Controller::Action::Response do
   end
 
   it 'can be converted into a JSON document' do
-    expect(response.to_json).to eq '{ "the": "result" }'
+    expect(JSON(response.to_json)).to eq("data" => %w[ fake-it ])
   end
 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.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - betterplace Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-16 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
@@ -297,7 +299,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.19
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Betterplace API documentation library