[OP-19749] Add API doc coverage tooling#24212
Draft
myabc wants to merge 13 commits into
Draft
Conversation
Grape represents slash-bearing segments (e.g. `actions/:id`) as splat
params (`*id`) and mounts a wildcard-method catch-all fallback. The
coverage normalizer left `*id` untouched and the extractor emitted the
catch-all, producing false undocumented/orphaned pairs. Splat params now
map to `{id}` like regular params, and only real HTTP-verb routes are
extracted.
The `op work-package create` CLI takes the subject positionally and requires a target project; the previous `--subject` flag is invalid and the call failed silently. Passes the subject positionally with a `--project` (from `OP_API_DOC_COVERAGE_PROJECT`), parses the created id from `--format json` with a text fallback, and raises on a non-zero `op` exit so filing failures surface instead of reporting false success.
myabc
force-pushed
the
code-maintenance/api-doc-fixes
branch
from
a98b2d5 to
b4d9d52
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces internal tooling to measure APIv3 documentation coverage by diffing the hand-written OpenAPI spec against the actual Grape routes, and adds rake tasks + supporting utilities (including optional work package filing) to report and track drift over time.
Changes:
- Add
api:docs:coverageandapi:docs:file_wpsrake tasks to generate JSON/Markdown reports and optionally file/update one WP per module with “hard” gaps. - Implement
OpenProject::ApiDocCoveragehelpers for extracting routes/spec endpoints, normalizing paths, diffing, and reporting results. - Add specs for the new extraction/diff/report/WP-filing components and document usage in APIv3 docs.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| spec/lib/open_project/api_doc_coverage/wp_filer_spec.rb | Unit specs for WP filing behavior and ledger interaction |
| spec/lib/open_project/api_doc_coverage/spec_extractor_spec.rb | Unit specs for extracting endpoints/params from OpenAPI hash |
| spec/lib/open_project/api_doc_coverage/route_extractor_spec.rb | Integration-ish specs for enumerating canonical APIv3 Grape routes |
| spec/lib/open_project/api_doc_coverage/reporter_spec.rb | Unit specs for JSON and Markdown reporting output |
| spec/lib/open_project/api_doc_coverage/path_normalizer_spec.rb | Unit specs for canonicalizing Grape paths and module naming |
| spec/lib/open_project/api_doc_coverage/ledger_spec.rb | Unit specs for persistent module→WP id storage |
| spec/lib/open_project/api_doc_coverage/ignore_list_spec.rb | Unit specs for ignoring configured endpoints |
| spec/lib/open_project/api_doc_coverage/file_wps_task_spec.rb | Task spec for api:docs:file_wps wiring and arguments |
| spec/lib/open_project/api_doc_coverage/differ_spec.rb | Unit specs for route/spec diffing behavior |
| spec/lib/open_project/api_doc_coverage/coverage_task_spec.rb | Task spec for generating report artifacts |
| lib/tasks/api_docs.rake | Adds rake tasks to generate coverage artifacts and file WPs |
| lib/open_project/api_doc_coverage/wp_filer.rb | Implements WP creation/update via op CLI with ledger tracking |
| lib/open_project/api_doc_coverage/spec_extractor.rb | Extracts endpoints/params from assembled OpenAPI spec |
| lib/open_project/api_doc_coverage/route_extractor.rb | Extracts documentable APIv3 endpoints from Grape routes |
| lib/open_project/api_doc_coverage/reporter.rb | Produces JSON and Markdown reports from diff results |
| lib/open_project/api_doc_coverage/path_normalizer.rb | Normalizes Grape route templates to canonical OpenAPI paths |
| lib/open_project/api_doc_coverage/ledger.rb | Persists module→WP id mapping for idempotent filing |
| lib/open_project/api_doc_coverage/ignore_list.rb | Filters out intentionally-undocumented endpoints |
| lib/open_project/api_doc_coverage/endpoint.rb | Defines lightweight Endpoint and Param data structures |
| lib/open_project/api_doc_coverage/differ.rb | Computes undocumented routes/params and orphaned paths |
| docs/api/apiv3/README.md | Documents the new coverage tasks and tiers of findings |
| docs/api/apiv3/.coverage-wps.yml | Adds initial WP ledger file for idempotent filing |
| docs/api/apiv3/.coverage-ignore.yml | Adds initial ignore list file for intentional gaps |
Comment on lines
+73
to
+75
| wp_id = parse_id(stdout) | ||
| @ledger.record(mod, wp_id) if wp_id | ||
| { module: mod, wp_id:, action: :created } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Work Package creation tasks contingent on opf/openproject-cli#15 being merged.
Adds tooling that diffs the hand-written APIv3 OpenAPI spec against the actual Grape routes, reporting drift in three tiers: hard (undocumented routes — the headline number), advisory (undocumented params on documented routes), and info (orphaned doc paths). Ships as rake tasks (
api:docs:*) plus a work package filer/ledger for filing the hard findings, and includes assorted APIv3 doc fixes surfaced while building the harness.Deliberately out of scope for this iteration: CI hard gate, fully-automatic work package filing, response-shape/status-code diffing, param type comparison.
Work package: https://community.openproject.org/wp/77263