Establish the LibreSign OpenAPI foundation for official SDKs
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 8/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Sôi nổi
- Công nghệ
- php, typescript
- Lĩnh vực
- api
Hướng nghiên cứu
This is a multi-stage epic, not a single task: it needs an approved ten-tag taxonomy applied through attributes in the PHP controllers under lib/Controller/, then a generated typescript-axios client evaluated for a Go/No-Go decision. Start by reading the controllers and the existing openapi.json, openapi-administration.json and openapi-full.json, and treat the epic's definition of done as the finish line. Do not hand-edit the generated OpenAPI or TypeScript files.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
Objective
Prepare LibreSign's PHP-owned OpenAPI contracts for the generation of official SDKs, starting with TypeScript. This foundational epic has two implementation outcomes:
- Classify every existing documented operation into an approved, functional SDK taxonomy.
- Generate and evaluate a real TypeScript Axios HTTP client from the resulting contract, producing reproducible test evidence and a Go/No-Go decision for official SDK infrastructure.
This epic does not publish an SDK.
Verified starting point
openapi.json: 68 default-scope operations.openapi-administration.json: 20 administration-scope operations.openapi-full.json: 88 combined operations, currently grouped under 16 controller-oriented tags.- OpenAPI specifications are extracted from PHP by
nextcloud/openapi-extractor; existing TypeScript definitions are generated byopenapi-typescript. - The existing OpenAPI workflow verifies regenerated files. PHPUnit API tests already use
byjg/swagger-test. - Contract hardening has already been done in PR #7662; do not repeat it.
Required deliverables
1. Classify the existing API into ten functional tags
Approved proposed groups, with expected operation counts:
| Tag | Operations |
|---|---|
policies |
17 |
identity |
14 |
documents |
6 |
requests |
5 |
signing |
8 |
appearance |
16 |
verification |
4 |
certificates |
12 |
notifications |
3 |
system |
3 |
| Total | 88 |
The taxonomy issue carries the exact old-tag-to-new-tag mapping, including per-method routing where one old tag splits into multiple domains. The Policy Workbench is a conceptual reference, not a set of OpenAPI tags.
Tags must be changed in PHP controller attributes under lib/Controller/. The OpenAPI JSON and generated TypeScript declarations are outputs of the existing generation process, not files to edit manually.
2. Generate and evaluate the TypeScript client
From the classified openapi-full.json, use a pinned OpenAPI Generator typescript-axios toolchain to generate TypeScript API methods, types and an Axios-backed transport client in a disposable location.
Verify generation, compilation, operation coverage, grouping, representative schema fidelity, request serialization, OCS paths/headers, custom base paths and non-OCS paths. Document unsupported request bodies (notably existing multipart upload limitations) and issue a reproducible Go/No-Go decision.
A successful CLI command alone is not evidence that the generated SDK is usable.
Engineering and CI boundaries
- PHP controllers remain the API source of truth; never patch generated OpenAPI artifacts by hand.
- Preserve HTTP paths/methods,
operationIdvalues, scopes, security requirements, parameters, request/response contracts and backend authorization. - Retain existing OpenAPI extractor and ByJG workflows. Do not require exhaustive coverage of 88 operations / 182 documented responses.
- No new PHP test generator, new test framework, database matrix or broad PHPUnit expansion.
- Keep generator validation focused and independently runnable; measure costs before suggesting a mandatory recurring CI step.
- Do not implement local OpenAPI multipart extractor workarounds while upstream support remains incomplete.
Long-term program direction — not part of this epic
The verified foundation will inform future work on:
- A dedicated, release-integrated SDK Generator with pinned inputs, reproducible builds and source provenance.
- An official, framework-independent TypeScript SDK with Nextcloud-compatible Axios injection.
- Migration of LibreSign-specific frontend API calls.
- Versioned Developer Manual API references, historical release notes, breaking changes, migration guidance and executable integration examples, with selection between supported stable release lines.
- Additional SDKs such as PHP and C# only when justified by real integration needs.
Keep application release version, supported Nextcloud version, HTTP API path version, OpenAPI document version and future SDK package version distinct. An SDK must be traceable to its originating LibreSign revision/contract.
Definition of done
- The complete functional taxonomy has been explicitly approved and applied in PHP controllers.
- The regenerated default, administration and full specifications preserve their existing operation inventories and HTTP contracts.
- TypeScript Axios client generation is reproducible from a pinned specification and toolchain.
- Generated API grouping, representative models and HTTP behavior have been tested, with limitations recorded.
- A documented Go/No-Go conclusion states whether
typescript-axiosis suitable for the next stage. - Relevant existing validation passes without unjustified recurring CI cost.
Mandatory handoff before closing
Review the implemented PHP attributes, generated contracts, client and compatibility findings together. Record the validated revision, generator version/configuration, capabilities and limitations, Axios/OCS integration requirements, upstream multipart dependencies, release compatibility assumptions and what the next SDK Generator implementation must deliver.
Only after this review prepare and decompose the next epic. On a No-Go outcome, revisit the generator/architecture before creating permanent SDK infrastructure.
Out of scope
Broad API contract-test coverage; automatic PHPUnit test generation; permanent SDK repositories; npm/Packagist/NuGet publication; production frontend migration; PHP/C# SDK implementation; multipart extractor development; implementation of versioned documentation navigation; and changing the LibreSign release process.
- Ngôn ngữ chính
- PHP
- Star
- 844
- Fork
- 176
- Merge trung bình
- 14 giờ 3 phút
- Pull request đã merge (30 ngày)
- 344
Chuẩn bị môi trường
Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của LibreSign/libresign
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
OpenSSL engine: leaf certificates get O=Internet Widgits Pty Ltd, ST=Some-State from system openssl.cnfCó thể đã có người làm @vitormattos đã nhận 5 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
LibreSign/libresign#9366 · 1 người được giao ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 83/100
LibreSign/libresign#9007 · 2 bình luận · 1 reaction ·
Maintainer thường phản hồi trong vòng 1 ngày
-
good first issue
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
LibreSign/libresign#8284 · 5 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
frontend javascript technical debt
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 8/100
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của LibreSign/libresign
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 79/100
Automattic/blocks-engine#6318 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
kind/enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
Maintainer thường phản hồi trong vòng 1 ngày
-
[remove-resource] Delete Open Course Hub, Open Multicourse Hub, and Learn2 with GitSync skeletonsĐang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
-
Allow @ in the service nameĐang mở
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 82/100