[lfals]

Resolves: #9088

📝 Summary

Applies the approved functional OpenAPI taxonomy to LibreSign controller operations via method-level #[OpenAPI(tags: [...])] attributes, then regenerates the OpenAPI specs.

Controller-name tags (account, admin, file, policy, …) are replaced by the ten functional tags used for SDK grouping: appearance, certificates, documents, identity, notifications, policies, requests, signing, system, and verification.

After syncing with main, also classifies the newer endpoints notify-status → notifications and signature_elements-use-saved-signature-elements → appearance.

Bumps nextcloud/openapi-extractor to stable v1.9.1 so scoped path merges keep both HTTP methods on the same path (fixes the previous GET/POST /footer-template full-spec omission). PHPUnit under tests/php/openapi/ enforces approved tags, uniqueness, scoped/full consistency (by operationId and route), and raw object equality—without a second operation inventory.

Current union counts:

Spec	Operations
openapi.json	69
openapi-administration.json	21
openapi-full.json	90
Union	90

Extractor 1.9.1 contract churn (no production behavior change)

All of the following come from regenerating with extractor v1.9.1; runtime handlers were not rewritten for these items:

• Implicit 401/403 responses: 41 new 401 responses in openapi.json; 19 401 + 19 403 in openapi-administration.json (OCS auth documentation).
• Boolean query parameters: former integer/enum [0,1] query params (a, forceIcon, mimeFallback, show*, file/list filters, deleteFile, …) are now documented as boolean. Nextcloud’s Dispatcher still accepts "true"/"1".
• Nullable formatting: default: null on nullable parameters; some nullable property $refs become allOf.
• Headers / prose: libresign-sign-request-uuid on signature/elements; CORS note text on two descriptions.
• Unused schemas removed from full: 11 unreferenced schemas dropped (DocMdpConfig, ReminderSettings, *WriteRequest, …). None were referenced from src/ outside generated types.
• New documented parameter: idDocApproval on POST /sign/uuid/{uuid}/code, bound as ?string and compared with === 'true' to match InjectionMiddleware.

🧪 How to test

1. Confirm PHP attributes under lib/Controller/ use only approved functional tags (and preserve existing scopes).
2. Regenerate and confirm the tree stays clean:

   composer run openapi
   git status --porcelain openapi*.json src/types/openapi/

3. Run the OpenAPI PHPUnit suite:

   vendor/bin/phpunit -c tests/php/openapi/phpunit.xml

4. Optional: open openapi-full.json in Swagger UI and verify functional grouping with no legacy tag sections.

Validation evidence

• Focused regression/acceptance test (tests/php/openapi, SignFileControllerTest)
• Relevant lint/type/static-analysis checks (composer psalm, npm run ts:check)
• Broader suite required by the changed surface
• CI reviewed

⚙️ API / Back-end changes

• Reclassified documented operations with functional OpenAPI tags in PHP controllers
• Regenerated openapi.json, openapi-administration.json, and openapi-full.json via composer openapi
• Unit and/or integration tests added or updated (tests/php/openapi)
• Authorization and negative paths checked when applicable (scopes/NoAdminRequired/routes preserved; idDocApproval keeps middleware semantics)
• Capabilities updated when applicable
• Documentation updated when applicable (AGENTS.md)
• API documentation regenerated with composer openapi when necessary

🚧 Tasks

• Apply approved tag mapping in PHP #[OpenAPI] attributes
• Bump openapi-extractor to ^1.9.1 and regenerate
• Require full = scoped union with no omission allowlist
• Reject tags outside APPROVED_TAGS (no LEGACY_TAGS)
• CI review on the draft PR

✅ Checklist

• I have read and followed the contribution guide.
• The diff does not contain unrelated refactors or generated changes.
• Commits follow Conventional Commits where applicable.
• All commits include the required DCO sign-off.

🤖 AI (if applicable)

• The content of this PR was partially or fully generated using AI

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-09T20:44:43.463261Z	00593aa	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a6d5213f07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[vitormattos]

Requesting changes to consolidate the OpenAPI taxonomy checks in the existing test infrastructure and ensure they are enforced by CI. No manual edits to generated OpenAPI JSON files are requested.

[vitormattos]

Please address the inline findings and keep functional OpenAPI tagging and auto-generated JSONs. The revised tests should accept a new correctly tagged endpoint without test-code changes, while rejecting invalid tags and duplicate IDs.

[vitormattos]

Additional file-specific cleanup suggestion.

[vitormattos]

Thank you for the work done so far, especially the move to PHPUnit and the improvements to the OpenAPI tag checks.

I have two follow-up comments for the next iteration: please fix the incomplete generated full specification at its source (rather than allowlisting the omission), and simplify the tag validation by removing the redundant legacy-tag inventory. The isolated PHPUnit configuration is fine as it is.

Could you please address these points, regenerate the specifications, and request another review when the CI checks have been rerun? Thanks again for the progress so far.