betterdocs 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43905ca43e64e65668831fed2e7c0d2eb1e0380347948c1d6f1aa7aa77bd8ea7
-  data.tar.gz: 6c52dcacf3ca65b2111f5e1da6655af8ab728c20e552ee90ca953e547c490699
+  metadata.gz: ad6f53d72b6b1dc91c3464a277c97992814fcc8b34a55f1fd043ace97b58c27a
+  data.tar.gz: '0259b534dece36526365a0861d2750c5ac5c5446e24920ef4113f67d4f00103a'
 SHA512:
-  metadata.gz: 493b9879a9c2bdcb1fd4d8858c59d34cf0a83eece18d15f1c7f005e84e57a127c101945c760cf0362d123b90006ecdcf2445a08cce586bd42cb882f4438d7df6
-  data.tar.gz: 4de261093b3b6b0cb4541d99e4d572cb239f41ca9091fbb41b9a2fc6df5be4e33d5a499ded80a19ac0f4bb740cb8709297ae145ee01a407c4ed8166c9ccebc47
+  metadata.gz: 8489c381f2cff832c4552f109f05c15fe092b95ea688025e98ef987ea4c714425dd981897b177ad6ad49d046c3166b20fb1cf10ac517a564373ca8080172fc89
+  data.tar.gz: a9858527e935a0ed22f82f218907a4010ad86a523de7504afa55890bc4dfed66a00347cec4f0ebe0aa7dd8587ec43cee441623bb874ae2686e86316a11725c06

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.11.0

data/betterdocs.gemspec

@@ -1,21 +1,21 @@
 # -*- encoding: utf-8 -*-
-# stub: betterdocs 0.10.0 ruby lib
+# stub: betterdocs 0.11.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterdocs".freeze
-  s.version = "0.10.0"
+  s.version = "0.11.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-07"
   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.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,12 @@ 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"
+    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

data/lib/betterdocs/version.rb

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

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 ] }
     )
   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,11 @@ 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
+
   it 'has data' do
     expect(response.data).to eq result_data
   end
@@ -54,6 +62,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: betterdocs
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - betterplace Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-16 00:00:00.000000000 Z
+date: 2022-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -297,7 +297,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