betterdocs 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72ab5a2d7d7981619a3c843d2f172e528f0aef5027ead1736f753e12852d3a30
-  data.tar.gz: 3779ee1e885cf02a5a086d5e827e806ff1861098bbbf69bfe6f7cc131e827ac9
+  metadata.gz: ad6f53d72b6b1dc91c3464a277c97992814fcc8b34a55f1fd043ace97b58c27a
+  data.tar.gz: '0259b534dece36526365a0861d2750c5ac5c5446e24920ef4113f67d4f00103a'
 SHA512:
-  metadata.gz: 5c1c34f5e91dbc70e8d0f26adf9013fd833333602dd757d969dc5ab63064d1cee0de2b54fb55d7c453c2498baaab25eea030a4b4f033ed97c9b0413fd1da5457
-  data.tar.gz: d6aec6c1162b05246c9ed558896fe7d4451fe403d43c1174958221f27da51c78810c1da66bf89b49d30eb6c88ea131849b53e09adf01ce54a3607141424fbac0
+  metadata.gz: 8489c381f2cff832c4552f109f05c15fe092b95ea688025e98ef987ea4c714425dd981897b177ad6ad49d046c3166b20fb1cf10ac517a564373ca8080172fc89
+  data.tar.gz: a9858527e935a0ed22f82f218907a4010ad86a523de7504afa55890bc4dfed66a00347cec4f0ebe0aa7dd8587ec43cee441623bb874ae2686e86316a11725c06

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 3.0.4
-bundler 2.3.8
+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.9.2
+0.11.0

data/betterdocs.gemspec

@@ -1,21 +1,21 @@
 # -*- encoding: utf-8 -*-
-# stub: betterdocs 0.9.2 ruby lib
+# stub: betterdocs 0.11.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterdocs".freeze
-  s.version = "0.9.2"
+  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-07-20"
+  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.13".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/generator/markdown.rb

@@ -102,7 +102,7 @@ module Betterdocs
 
       def render_to(filename, template, binding)
         File.open(filename, 'w') do |output|
-          rendered = ERB.new(template, nil, '-').result(binding)
+          rendered = ERB.new(template, trim_mode: '-').result(binding)
           output.write rendered
         end
         self

data/lib/betterdocs/version.rb

@@ -1,6 +1,6 @@
 module Betterdocs
   # Betterdocs version
-  VERSION         = '0.9.2'
+  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.9.2
+  version: 0.11.0
 platform: ruby
 authors:
 - betterplace Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-20 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.13
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Betterplace API documentation library