Fixes #36575 - Use apipie-dsl default model descriptions

[archanaserver]

This pull request updates the apipie-dsl gem to version 2.6.1 and makes configuration changes to enhance our API documentation.

[ekohl]

I'd squash this in a single commit, but in the same commit also remove all places where the model description is currently set. Otherwise the default will never be used. Then the summary of the commit would be to something like Use apipie-dsl default model descriptions.

[ekohl]

This is indeed roughly what I would expect. There are 2 more cases I see:

$ rg 'A class represent'
config/initializers/apipie.rb
30:  config.default_class_description = ->(model) { _("A class representing %s object") % model.human }

app/models/hostgroup.rb
86:  apipie :class, "A class representing #{model_name.human} object" do

app/models/subnet.rb
127:  apipie :class, "A class representing #{model_name.human} object" do

app/models/ptable.rb
64:  apipie :class, desc: 'A class representing Partition Table object' do

app/models/nic/base.rb
83:    apipie :class, 'A class representing Network Interface Controller object' do

app/models/host/base.rb
80:    apipie :class, 'A class representing base Host object' do

app/models/host/managed.rb
106:  apipie :class, 'A class representing managed Host object' do

So app/models/hostgroup.rb and app/models/subnet.rb are also candidates.

[ekohl]

Test failure looks related:

[2023-10-20T09:35:11.463Z] NoMethodError: undefined method `human' for User (call 'User.connection' to establish a connection):Class
[2023-10-20T09:35:11.463Z] /usr/local/rvm/gems/ruby-2.7.4@foreman-pr-unit-test-1661-2/gems/activerecord-6.1.7.6/lib/active_record/dynamic_matchers.rb:22:in `method_missing'

[archanaserver]

Test failure looks related:

[2023-10-20T09:35:11.463Z] NoMethodError: undefined method `human' for User (call 'User.connection' to establish a connection):Class
[2023-10-20T09:35:11.463Z] /usr/local/rvm/gems/ruby-2.7.4@foreman-pr-unit-test-1661-2/gems/activerecord-6.1.7.6/lib/active_record/dynamic_matchers.rb:22:in `method_missing'

@ekohl I'm not sure where you're pointing it to, Can you please explain?

[ekohl]

@ekohl I'm not sure where you're pointing it to, Can you please explain?

I opened the unit test results. The current one fails with another error (https://ci.theforeman.org/blue/organizations/jenkins/foreman-pr-unit-test/detail/foreman-pr-unit-test/1672/pipeline/) but I also see this in the Katello failure:

[2023-10-23T09:03:10.156Z] NotImplementedError: Katello::Model is an abstract class and cannot be instantiated.
[2023-10-23T09:03:10.156Z] /usr/local/rvm/gems/ruby-2.7.4@foreman-pr-katello-test-1695/gems/activerecord-6.1.7.6/lib/active_record/inheritance.rb:54:in `new'
[2023-10-23T09:03:10.156Z] /home/jenkins/workspace/foreman-pr-katello-test/foreman/config/initializers/apipie.rb:24:in `block (2 levels) in <top (required)>'
[2023-10-23T09:03:10.156Z] /usr/local/rvm/gems/ruby-2.7.4@foreman-pr-katello-test-1695/gems/apipie-dsl-2.6.0/lib/apipie_dsl/dsl.rb:469:in `apipie'
[2023-10-23T09:03:10.156Z] /home/jenkins/workspace/foreman-pr-katello-test/app/models/katello/model.rb:6:in `<class:Model>'
[2023-10-23T09:03:10.156Z] /home/jenkins/workspace/foreman-pr-katello-test/app/models/katello/model.rb:2:in `<module:Katello>'
[2023-10-23T09:03:10.156Z] /home/jenkins/workspace/foreman-pr-katello-test/app/models/katello/model.rb:1:in `<top (required)>'

[ekohl]

And we're back to this error:

[2023-10-26T09:52:26.458Z] rake aborted!
[2023-10-26T09:52:26.458Z] NoMethodError: undefined method `human' for User (call 'User.connection' to establish a connection):Class

@ofedoren I think that it calls the descriptions during the initializer is a problem and a blocker to using this feature. Do you agree?

@archanaserver perhaps you can look in apipie-dsl itself to see if this can be fixed.

[archanaserver]

And we're back to this error:

[2023-10-26T09:52:26.458Z] rake aborted!
[2023-10-26T09:52:26.458Z] NoMethodError: undefined method `human' for User (call 'User.connection' to establish a connection):Class

@ofedoren I think that it calls the descriptions during the initializer is a problem and a blocker to using this feature. Do you agree?

@archanaserver perhaps you can look in apipie-dsl itself to see if this can be fixed.

@ekohl @ofedoren I didn't find anything related to this issue. Could you please point me in the right direction? I'll take another look.

[ofedoren]

I've released apipie-dsl 2.6.1 with a fix to postpone default description block evaluation until the actual description renders. It should help for most of the time.

Although, there should be a slight change in config here. Please see inline.

[ofedoren]

Suggested change

	config.default_class_description = ->(model) { _("A class representing %s object") % model.human }
	config.default_class_description = ->(model) do
	return nil unless model.respond_to?(:model_name)
	_("A class representing %s object") % model.model_name.human
	end

It appears that model doesn't necessary respond to human, but rather should respond (in case it's ActiveRecord) to model_name, which returns some wrapper, which responds to human.

[ekohl]

This should at least require 2.6.1

Suggested change

	gem 'apipie-dsl', '>= 2.6.0'
	gem 'apipie-dsl', '>= 2.6.1'

[ekohl]

I think RuboCop wants to use lambda:

Suggested change

	config.default_class_description = ->(model) do
	config.default_class_description = lambda do |model|

See https://docs.rubocop.org/rubocop/1.57/cops_style.html#stylelambda as well

[ekohl]

Packit fails to build because it wasn't rebased, but that's not blocking here.

[ofedoren]

Nothing to add from my side, thanks a lot! Let's get this in.