I am interested in hearing people's opinion's about how to best maintain
the example data for the API documentation.
The great apipie gem automatically generates documentation of the sample
JSON responses from the fixtures. On one hand, this is great. On the other
hand, what if we don't want all the fixtures test data to be in the
documentation.
Some options include:
Maintain a separate set of fixtures for documentation purposes
Maintain a separate development database of sample data for
documentation purposes
Manually edit and maintain the apipie_examples.yml file which is
generated by apipie.
Hey, AFAIK including the example in the doco is turned off by default
and you need to explicitly specify you want it. So if you don't want it,
you now know what to do
Ivan, correct me if I am wrong.
···
On Thu, Nov 08, 2012 at 07:51:12AM -0800, Joseph Magen wrote:
> The great apipie gem automatically generates documentation of the sample
> JSON responses from the fixtures. On one hand, this is great. On the other
> hand, what if we don't want all the fixtures test data to be in the
> documentation.
>
> Some options include:
> 1) Maintain a separate set of fixtures for documentation purposes
> 2) Maintain a separate development database of sample data for
> documentation purposes
> 3) Manually edit and maintain the apipie_examples.yml file which is
> generated by apipie.
I missed this message originally, sorry for the delay. By default, only
the first example is shown in the documentation. show_in_doc attribute
at each example controls this.
What you can do is to run the example data though some script to modify
what examples should be included (or excluded). Any manual work here
might be frustrating so every automation is worth the effort.
– Ivan
···
On 11/14/2012 02:54 PM, Lukas Zapletal wrote:
> On Thu, Nov 08, 2012 at 07:51:12AM -0800, Joseph Magen wrote:
>> The great apipie gem automatically generates documentation of the sample
>> JSON responses from the fixtures. On one hand, this is great. On the other
>> hand, what if we don't want all the fixtures test data to be in the
>> documentation.
>>
>> Some options include:
>> 1) Maintain a separate set of fixtures for documentation purposes
>> 2) Maintain a separate development database of sample data for
>> documentation purposes
>> 3) Manually edit and maintain the apipie_examples.yml file which is
>> generated by apipie.
> Hey, AFAIK including the example in the doco is turned off by default
> and you need to explicitly specify you want it. So if you don't want it,
> you now know what to do :-)
>
> Ivan, correct me if I am wrong.
>
I am writing a sample engine/plugin for Foreman that
adds one instance method to the Host model class
adds one instance method to the HostsController class
adds one route
I did it two ways and wanted to discuss which way we want to recommend for a wiki page on plugin engines
Inherit from parent classes
module ForemanReserve
class Host < ::Host
# def new_method
end
end
module ForemanReserve
class HostsController < ::HostsController
# def new_method
end
end
Mixin modules into parent classes
module ForemanReserve
module HostExtensions
extend ActiveSupport::Concern
module InstanceMethods
# def new_method
end
end
end
::Host.send :include, ForemanReserve::HostExtensions
module ForemanReserve
module HostsControllerExtensions
extend ActiveSupport::Concern
module InstanceMethods
# def new_method
end
end
end
::HostsController.send :include, ForemanReserve::HostsControllerExtensions
From some stuff I've read, it appears that mixins are the preferred way. However, I think subclassing is easier at least for the controller, since the new engine route can call the namespaced engine controller. If a mixin is used, then the engine route needs to call the "non-namespaced" main app controller.
What do people think about subclassing controllers and using mixins for models? Any thoughts would be helpful.
>
> I am writing a sample engine/plugin for Foreman that
> - adds one instance method to the Host model class
> - adds one instance method to the HostsController class
> - adds one route
>
> I did it two ways and wanted to discuss which way we want to recommend for
> a wiki page on plugin engines
>
> 1) Inherit from parent classes
>
> module ForemanReserve
> class Host < ::Host
>
IMHO this is wrong, as you end up with issues like when using STI
so if you have a type (e.g. a compute resource) you'll end up with
ForemanReserver::ComputeResource instead.
> # def new_method
> end
end
>
> module ForemanReserve
> class HostsController < ::HostsController
>
Again, not sure if this makes sense, do you want to inherit all controller
filters etc? if not, then it makes no sense.
> # def new_method
> end
> end
>
>
> 2) Mixin modules into parent classes
>
> module ForemanReserve
> module HostExtensions
> extend ActiveSupport::Concern
> module InstanceMethods
> # def new_method
> end
> end
> end
> ::Host.send :include, ForemanReserve::HostExtensions
>
> module ForemanReserve
> module HostsControllerExtensions
> extend ActiveSupport::Concern
> module InstanceMethods
> # def new_method
> end
> end
> end
> ::HostsController.send :include, ForemanReserve::HostsControllerExtensions
>
>
> From some stuff I've read, it appears that mixins are the preferred way.
> However, I think subclassing is easier at least for the controller, since
> the new engine route can call the namespaced engine controller. If a mixin
> is used, then the engine route needs to call the "non-namespaced" main app
> controller.
>
> What do people think about subclassing controllers and using mixins for
> models? Any thoughts would be helpful.
>
+1 for mixins, with +1 to using ActiveSupport::Concern
Ohad
···
On Thursday, 29 November 2012 15:48:51 UTC+2, Joseph Magen wrote:
