In Foreman and every plugin with an API uses apipie-rails. This describes the API (locations, methods, parameters). It can also generate human readable documentation that’s served on
/apidoc and what we also provide on apidocs.theforeman.org.
To do this, Foreman generates apidocs and ships them in its package. The same is done for every plugin.
Then after installation the indexes are regenerated (using the
apipie:cache:index rake task). This is because there’s an index page with all endpoints that can only be assembled once you know which plugins are present. There is also a JSON file which has the complete description, which again can only be generated with all plugins present.
This is also the reason why it’s generally recommended to visit
/apidoc on your own instance rather then our apidocs: they document your installed plugins.
Katello behaves differently depending on which content types are present. This means some parts are only visible if Pulp is installed with Debian or OSTree support. For the UI this works well, because that’s generated dynamically anyway.
The problem appears in the API documentation. During package building it’s not known yet which content types are available. That means it’s incomplete.
An example is always clearer:
RepositoryTypeManager.removable_content_types(false).map(&:label) is executed during packaging and only the types available during packaging are visible by default. There may be more examples.
In https://github.com/theforeman/puppet-foreman_proxy_content/pull/393 we at least set up some events that when a content type is added the index is refreshed, but realistically this isn’t going to cover everything.
It is possible to make Katello generate all options. This could be achieved by pretending all types are present during packaging. This would generate complete API documentation, but it may be too broad.
This could be seen as a workaround.
It is possible to run the
apipie:cache (which is what packaging does). This is slow: on my machine with Katello it took about 50 seconds per language plus some other common overhead. It would also need to be done after every Foreman/plugin package installation which makes it very expensive.
Not a solution I’d like to see due to the cost for end user systems
Essentially this is like a caching problem. apipie-rails can generate the apidocs on the fly. This is what happens in development. It’s technically a bit slower, but given how little the apidocs are used it’s probably an acceptable overhead.
Perhaps the JSON view (as used by Hammer, FAM and other apipie clients) could be cached by Foreman using its regular caching system (file based by default, possibly memcache or Redis).
This would also have faster package builds and smaller packages (thus faster installation) as an advantage.
This sounds like a costly rewrite that would take time.
I’m leaning to investigate option 3 (disabling the cache) but perhaps I’m missing another solution. I’ll readily admit I’m not too familiar with it.