Problem/Motivation

The doc module routes are currently statically defined for the default supported modules. This is limiting and results in redundant classes naming. These should be refactored into dynamically generated routes using plugins.

Proposed resolution

Plugins

In #2874877: Refactor OpenApiController, we introduced plugins for managing generators. Implemented a plugin for docs modules could provide dynamic functionality and allow other ui type modules to be built around the openapi specs.

Routes

Using plugins for generators allowed us to convert the routes for the downloads into a single dynamic route with a dynamic param. Using plugins for the doc uis we can achieve a similar simplicity. A single route could be provided by core, which would take both a generator and a doc plugin and produce the same result.

The only challenge presented by the current implementation is that the SwaggerUi module provides two different implementations. For Jsonapi, it provides a single url for details on all endpoints. However, for REST it provides a url for each for each of the available entity types. This means that a plugin type design is not available here.

This per entity implementation however is an interesting thought. Since we already allow filtering of the download doc based upon entity, this functionality can be preserved by allowing the same filter params to be added to the generic doc for the rest+swagger docs ui. That filter chunk can then be passed to the download controller and the output can be used to display the docs. This allows us to generate the range of doc pages while limiting the number of routes that we are generating. This also allows us to extend this function into the json api docs. Additionally if we implemented this in a top level controller, we could also extend this into the reDoc module as well.

Remaining tasks

  1. Replace Doc urls with unified route, using the OpenAPI UI module.
  2. Remove the ReDoc and Swagger modules, as they have been replaced.
  3. Developer installation steps to remove the old modules and install the new modules, if they are present. If not, we want to alert the user and fail the database update the admin either installed the new library or uninstalls the module via another method.
  4. Publish a Change Record and Release to remove this feature.

User interface changes

We will be eliminating the swagger_ui.rest.list route and replacing it with extended filtering functionality. We may wish to provide either a similar listing page or to provide a filter option on the actual page to allow the user to select the filter params for the ui. This will as a result eliminate the need for #2874891: Allow filtering doc pages per resource.

API changes

This will not result in any critical changes to the api, but will provide more extensible resources for module developers to extend the openapi functionality.

CommentFileSizeAuthor
#4 2948570-4-refactor-doc-modules.patch31.21 KBrichgerdes

Comments

richgerdes created an issue. See original summary.

richgerdes’s picture

I have just published a new module, OpenAPI UI, which abstracts away the integration with the Doc modules, and factors them into plugins, which was part of the planned implementation for this issue.

The next step here, is to remove the integrations with the UI modules from this project and consolidate the ui display into a single uniform system. We will still need to contain logic for display of the UI since the new project only allows low level support for multiple libraries via a render element.

I have already started the basic implementation of the UI (while developing the new module). I will then need to strip out the old modules, publish a release and change record since its a fairly substantial change to the underlying system, which will no longer exist in this project.

richgerdes’s picture

richgerdes’s picture

StatusFileSize
new31.21 KB

The attached patch removes the openapi sub modules, and converts the ui routes to work using the OpenAPI UI module and its extensions.

richgerdes’s picture

Status: Active » Needs review

  • richgerdes authored 5a7c11e on 8.x-1.x
    Issue #2948570 by richgerdes: Refactor doc module implementations
    
richgerdes’s picture

Issue summary: View changes

These changes have been committed and pushed. I have also published a change record to document this change. Additionally I am tagging a beta2 release since this is a major change to the module.

richgerdes’s picture

Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.