Problem/Motivation

The module ships two OpenAPI generator plugins, and the documentation of what they need to run is wrong in both places it is written.

  • composer.json suggests drupal/openapi with the line "provides the OpenAPI generator base class that the module's generators extend". It does not: openapi defines the plugin type and the two administration pages, while the base class the generators extend - RestGenerator - comes from drupal/openapi_rest, which is not suggested at all and which brings schemata and schemata_json_schema with it.
  • The README says "ensure the openapi module is installed", which is not enough to make the page work, and its table of optional modules repeats the same wrong attribution.

Two things are missing beside the names. Nothing says that the endpoints have to be enabled as REST resources before the generated document has any paths in it - on a site where none are, the page renders and the document is empty, which reads as a broken generator. And nothing says that a resource must be enabled only for the methods it implements: openapi_rest answers a resource configured for a method it has no route for with No route found for REST resource, X, for method POST and no document at all.

Proposed resolution

  • Suggest drupal/openapi_rest and say what it is for; correct the line on drupal/openapi to what that module actually provides.
  • Require the documentation stack in require-dev, so the pipeline installs it and the generators can be covered by a test rather than only by hand.
  • Cover the generator with a test that builds the document and asserts the endpoints of this module are in it, skipped when the modules are absent.
  • Say the same thing in the README and in hook_help(): which modules the documentation page needs, that the endpoints are switched on at /admin/config/services/rest and that a resource is enabled for the methods it implements.
  • Name the core REST administration UI for what it is - a convenience of the site rather than an integration of this module - so that the list of optional modules stays a list of integrations.

Remaining tasks

Everything.

Issue fork myrest-3619449

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

sergeydruua created an issue. See original summary.

  • sergeydruua committed d3b2cbcd on 1.0.x
    Issue #3619449: Name the modules the API documentation needs and how...
sergeydruua’s picture

Status: Active » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

sergeydruua’s picture

Status: Fixed » Closed (fixed)