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.jsonsuggestsdrupal/openapiwith the line "provides the OpenAPI generator base class that the module's generators extend". It does not:openapidefines the plugin type and the two administration pages, while the base class the generators extend -RestGenerator- comes fromdrupal/openapi_rest, which is not suggested at all and which bringsschemataandschemata_json_schemawith it.- The README says "ensure the
openapimodule 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_restand say what it is for; correct the line ondrupal/openapito 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/restand 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
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
Comment #4
sergeydruua commentedComment #6
sergeydruua commented