Skip to content

Commit 740073a

Browse files
vitormattosvitormattos
authored
Merge pull request #7668 from LibreSign/fix/openapi-signatureflow-structure
fix: align OpenAPI contract and frontend to string-only signatureFlow
2 parents da3a421 + 91dca6d commit 740073a

44 files changed

Lines changed: 794 additions & 3382 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎lib/Controller/AdminController.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
use UnexpectedValueException;
4646

4747
/**
48-
* @psalm-import-type LibresignCetificateDataGenerated from \OCA\Libresign\ResponseDefinitions
48+
* @psalm-import-type LibresignCertificateDataGenerated from \OCA\Libresign\ResponseDefinitions
4949
* @psalm-import-type LibresignCertificateEngineConfigResponse from \OCA\Libresign\ResponseDefinitions
5050
* @psalm-import-type LibresignCertificatePolicyResponse from \OCA\Libresign\ResponseDefinitions
5151
* @psalm-import-type LibresignConfigureCheck from \OCA\Libresign\ResponseDefinitions
@@ -225,7 +225,7 @@ private function generateCertificate(
225225
*
226226
* Return all data of root certificate and a field called `generated` with a boolean value.
227227
*
228-
* @return DataResponse<Http::STATUS_OK, LibresignCetificateDataGenerated, array{}>
228+
* @return DataResponse<Http::STATUS_OK, LibresignCertificateDataGenerated, array{}>
229229
*
230230
* 200: OK
231231
*/
@@ -666,7 +666,7 @@ public function deleteCertificatePolicy(): DataResponse {
666666
* 422: Validation error
667667
*/
668668
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/admin/certificate-policy/oid', requirements: ['apiVersion' => '(v1)'])]
669-
public function updateOID(string $oid): DataResponse {
669+
public function updateOid(string $oid): DataResponse {
670670
try {
671671
$this->certificatePolicyService->updateOid($oid);
672672
return new DataResponse(

‎lib/Controller/CrlApiController.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
use OCP\AppFramework\Http;
1515
use OCP\AppFramework\Http\Attribute\ApiRoute;
1616
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
17+
use OCP\AppFramework\Http\Attribute\OpenAPI;
1718
use OCP\AppFramework\Http\DataResponse;
1819
use OCP\IRequest;
1920
use OCP\IUserSession;
@@ -51,6 +52,7 @@ public function __construct(
5152
* 200: CRL entries retrieved successfully
5253
*/
5354
#[NoCSRFRequired]
55+
#[OpenAPI(tags: ['crl'])]
5456
#[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/crl/list', requirements: ['apiVersion' => '(v1)'])]
5557
public function list(
5658
?int $page = null,
@@ -98,6 +100,7 @@ public function list(
98100
* 404: Certificate not found
99101
*/
100102
#[NoCSRFRequired]
103+
#[OpenAPI(tags: ['crl'])]
101104
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/crl/revoke', requirements: ['apiVersion' => '(v1)'])]
102105
public function revoke(
103106
string $serialNumber,

‎lib/Controller/DevelopController.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
use OCP\AppFramework\Http;
1414
use OCP\AppFramework\Http\Attribute\FrontpageRoute;
1515
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
16+
use OCP\AppFramework\Http\Attribute\OpenAPI;
1617
use OCP\AppFramework\Http\Attribute\PublicPage;
1718
use OCP\AppFramework\Http\DataResponse;
1819
use OCP\AppFramework\Http\FileDisplayResponse;
@@ -21,6 +22,7 @@
2122
use OCP\IConfig;
2223
use OCP\IRequest;
2324

25+
#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
2426
class DevelopController extends Controller {
2527
public function __construct(
2628
IRequest $request,

‎lib/Controller/FileController.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -775,7 +775,7 @@ private function extractFileName(array $fileData): string {
775775
#[NoCSRFRequired]
776776
#[RequireManager]
777777
#[ApiRoute(verb: 'DELETE', url: '/api/{apiVersion}/file/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
778-
public function deleteAllRequestSignatureUsingFileId(int $fileId, bool $deleteFile = true): DataResponse {
778+
public function deleteFile(int $fileId, bool $deleteFile = true): DataResponse {
779779
try {
780780
$data = [
781781
'userManager' => $this->userSession->getUser(),

‎lib/Controller/FileElementController.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ public function __construct(
5757
#[NoAdminRequired]
5858
#[NoCSRFRequired]
5959
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/file-element/{uuid}', requirements: ['apiVersion' => '(v1)'])]
60-
public function post(string $uuid, int $signRequestId, ?int $elementId = null, ?int $fileId = null, string $type = '', array $metadata = [], array $coordinates = []): DataResponse {
60+
public function createVisibleElement(string $uuid, int $signRequestId, ?int $elementId = null, ?int $fileId = null, string $type = '', array $metadata = [], array $coordinates = []): DataResponse {
6161
$visibleElement = [
6262
'elementId' => $elementId,
6363
'type' => $type,
@@ -108,8 +108,8 @@ public function post(string $uuid, int $signRequestId, ?int $elementId = null, ?
108108
#[NoAdminRequired]
109109
#[NoCSRFRequired]
110110
#[ApiRoute(verb: 'PATCH', url: '/api/{apiVersion}/file-element/{uuid}/{elementId}', requirements: ['apiVersion' => '(v1)'])]
111-
public function patch(string $uuid, int $signRequestId, ?int $elementId = null, ?int $fileId = null, string $type = '', array $metadata = [], array $coordinates = []): DataResponse {
112-
return $this->post($uuid, $signRequestId, $elementId, $fileId, $type, $metadata, $coordinates);
111+
public function updateVisibleElement(string $uuid, int $signRequestId, ?int $elementId = null, ?int $fileId = null, string $type = '', array $metadata = [], array $coordinates = []): DataResponse {
112+
return $this->createVisibleElement($uuid, $signRequestId, $elementId, $fileId, $type, $metadata, $coordinates);
113113
}
114114

115115
/**
@@ -127,7 +127,7 @@ public function patch(string $uuid, int $signRequestId, ?int $elementId = null,
127127
#[NoAdminRequired]
128128
#[NoCSRFRequired]
129129
#[ApiRoute(verb: 'DELETE', url: '/api/{apiVersion}/file-element/{uuid}/{elementId}', requirements: ['apiVersion' => '(v1)'])]
130-
public function delete(string $uuid, int $elementId): DataResponse {
130+
public function deleteVisibleElement(string $uuid, int $elementId): DataResponse {
131131
try {
132132
$this->validateHelper->validateExistingFile([
133133
'uuid' => $uuid,

‎lib/Controller/IdDocsController.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ public function delete(int $nodeId, ?string $uuid = null): DataResponse {
152152
#[NoCSRFRequired]
153153
#[RequireSignRequestUuid(skipIfAuthenticated: true)]
154154
#[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/id-docs', requirements: ['apiVersion' => '(v1)'])]
155-
public function listOfUnauthenticatedSigner(
155+
public function listUnauthenticatedSignerDocuments(
156156
?string $userId = null,
157157
?int $signRequestId = null,
158158
?int $page = null,

‎lib/Controller/PageController.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
use OCP\AppFramework\Http\Attribute\FrontpageRoute;
3535
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
3636
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
37+
use OCP\AppFramework\Http\Attribute\OpenAPI;
3738
use OCP\AppFramework\Http\Attribute\PublicPage;
3839
use OCP\AppFramework\Http\ContentSecurityPolicy;
3940
use OCP\AppFramework\Http\DataResponse;
@@ -49,6 +50,7 @@
4950
use OCP\Util;
5051
use Psr\Log\LoggerInterface;
5152

53+
#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
5254
class PageController extends AEnvironmentPageAwareController {
5355
public function __construct(
5456
IRequest $request,

‎lib/Controller/RequestSignatureController.php‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
use OCP\AppFramework\Http\Attribute\ApiRoute;
2121
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
2222
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
23+
use OCP\AppFramework\Http\Attribute\OpenAPI;
2324
use OCP\AppFramework\Http\DataResponse;
2425
use OCP\IL10N;
2526
use OCP\IRequest;
@@ -76,8 +77,9 @@ public function __construct(
7677
#[NoAdminRequired]
7778
#[NoCSRFRequired]
7879
#[RequireManager]
80+
#[OpenAPI(tags: ['signing'])]
7981
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/request-signature', requirements: ['apiVersion' => '(v1)'])]
80-
public function request(
82+
public function requestSignature(
8183
array $signers = [],
8284
string $name = '',
8385
array $settings = [],
@@ -131,7 +133,7 @@ public function request(
131133
* @param LibresignNewSigner[]|null $signers Collection of signers who must sign the document. Use identifyMethods as the canonical format.
132134
* @param string|null $uuid UUID of sign request. The signer UUID is what the person receives via email when asked to sign. This is not the file UUID.
133135
* @param LibresignVisibleElement[]|null $visibleElements Visible elements on document
134-
* @param LibresignNewFile|array<empty>|null $file File object. Supports nodeId, url, base64 or path when creating a new request.
136+
* @param LibresignNewFile|null $file File object. Supports nodeId, url, base64 or path when creating a new request.
135137
* @param integer|null $status Numeric code of status * 0 - no signers * 1 - signed * 2 - pending
136138
* @param string|null $signatureFlow Signature flow mode: 'parallel' or 'ordered_numeric'. If not provided, uses global configuration
137139
* @param string|null $name The name of file to sign
@@ -145,12 +147,13 @@ public function request(
145147
#[NoAdminRequired]
146148
#[NoCSRFRequired]
147149
#[RequireManager]
150+
#[OpenAPI(tags: ['signing'])]
148151
#[ApiRoute(verb: 'PATCH', url: '/api/{apiVersion}/request-signature', requirements: ['apiVersion' => '(v1)'])]
149-
public function updateSign(
152+
public function updateSignatureRequest(
150153
?array $signers = [],
151154
?string $uuid = null,
152155
?array $visibleElements = null,
153-
?array $file = [],
156+
?array $file = null,
154157
?int $status = null,
155158
?string $signatureFlow = null,
156159
?string $name = null,
@@ -160,6 +163,7 @@ public function updateSign(
160163
try {
161164
$user = $this->userSession->getUser();
162165
$signers = is_array($signers) ? $signers : [];
166+
$file = is_array($file) ? $file : [];
163167

164168
if (empty($uuid)) {
165169
return $this->createSignatureRequest(
@@ -212,7 +216,7 @@ public function updateSign(
212216

213217
/**
214218
* Internal method to handle signature request creation logic
215-
* Used by both request() and updateSign() when creating new requests
219+
* Used by both requestSignature() and updateSignatureRequest() when creating new requests
216220
*
217221
* @return DataResponse<Http::STATUS_OK, LibresignDetailedFileResponse, array{}>
218222
* @throws LibresignException
@@ -289,8 +293,9 @@ private function createSignatureRequest(
289293
#[NoAdminRequired]
290294
#[NoCSRFRequired]
291295
#[RequireManager]
296+
#[OpenAPI(tags: ['signing'])]
292297
#[ApiRoute(verb: 'DELETE', url: '/api/{apiVersion}/sign/file_id/{fileId}/{signRequestId}', requirements: ['apiVersion' => '(v1)'])]
293-
public function deleteOneRequestSignatureUsingFileId(int $fileId, int $signRequestId): DataResponse {
298+
public function removeSigner(int $fileId, int $signRequestId): DataResponse {
294299
try {
295300
$data = [
296301
'userManager' => $this->userSession->getUser(),
@@ -332,8 +337,9 @@ public function deleteOneRequestSignatureUsingFileId(int $fileId, int $signReque
332337
#[NoAdminRequired]
333338
#[NoCSRFRequired]
334339
#[RequireManager]
340+
#[OpenAPI(tags: ['signing'])]
335341
#[ApiRoute(verb: 'DELETE', url: '/api/{apiVersion}/sign/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
336-
public function deleteAllRequestSignatureUsingFileId(int $fileId): DataResponse {
342+
public function deleteSignatureRequest(int $fileId): DataResponse {
337343
try {
338344
$data = [
339345
'userManager' => $this->userSession->getUser(),

‎lib/Controller/SignFileController.php‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
use OCP\AppFramework\Http\Attribute\ApiRoute;
3232
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
3333
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
34+
use OCP\AppFramework\Http\Attribute\OpenAPI;
3435
use OCP\AppFramework\Http\Attribute\PublicPage;
3536
use OCP\AppFramework\Http\DataResponse;
3637
use OCP\IL10N;
@@ -83,8 +84,9 @@ public function __construct(
8384
#[NoCSRFRequired]
8485
#[RequireManager]
8586
#[PublicPage]
87+
#[OpenAPI(tags: ['signing'])]
8688
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/sign/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
87-
public function signUsingFileId(int $fileId, string $method, array $elements = [], string $identifyValue = '', string $token = '', bool $async = false): DataResponse {
89+
public function signByFileId(int $fileId, string $method, array $elements = [], string $identifyValue = '', string $token = '', bool $async = false): DataResponse {
8890
return $this->sign($method, $elements, $identifyValue, $token, $fileId, null, $async);
8991
}
9092

@@ -107,8 +109,9 @@ public function signUsingFileId(int $fileId, string $method, array $elements = [
107109
#[NoCSRFRequired]
108110
#[RequireSigner]
109111
#[PublicPage]
112+
#[OpenAPI(tags: ['signing'])]
110113
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/sign/uuid/{uuid}', requirements: ['apiVersion' => '(v1)'])]
111-
public function signUsingUuid(string $uuid, string $method, array $elements = [], string $identifyValue = '', string $token = '', bool $async = false): DataResponse {
114+
public function signBySignerUuid(string $uuid, string $method, array $elements = [], string $identifyValue = '', string $token = '', bool $async = false): DataResponse {
112115
return $this->sign($method, $elements, $identifyValue, $token, null, $uuid, $async);
113116
}
114117

@@ -253,6 +256,7 @@ private function signSync($libreSignFile, array $elements, array $metadata): Dat
253256
#[NoCSRFRequired]
254257
#[PublicPage]
255258
#[CanSignRequestUuid]
259+
#[OpenAPI(tags: ['signing'])]
256260
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/sign/uuid/{uuid}/renew/{method}', requirements: ['apiVersion' => '(v1)'])]
257261
public function signRenew(string $method): DataResponse {
258262
$this->signFileService->renew(
@@ -283,8 +287,9 @@ public function signRenew(string $method): DataResponse {
283287
#[NoCSRFRequired]
284288
#[RequireSigner]
285289
#[PublicPage]
290+
#[OpenAPI(tags: ['signing'])]
286291
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/sign/uuid/{uuid}/code', requirements: ['apiVersion' => '(v1)'])]
287-
public function getCodeUsingUuid(string $uuid, ?string $identifyMethod, ?string $signMethod, ?string $identify): DataResponse {
292+
public function requestCodeBySignerUuid(string $uuid, ?string $identifyMethod, ?string $signMethod, ?string $identify): DataResponse {
288293
try {
289294
$signRequest = $this->signRequestMapper->getBySignerUuidAndUserId($uuid);
290295
} catch (\Throwable) {
@@ -309,8 +314,9 @@ public function getCodeUsingUuid(string $uuid, ?string $identifyMethod, ?string
309314
#[NoCSRFRequired]
310315
#[RequireSigner]
311316
#[PublicPage]
317+
#[OpenAPI(tags: ['signing'])]
312318
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/sign/file_id/{fileId}/code', requirements: ['apiVersion' => '(v1)'])]
313-
public function getCodeUsingFileId(int $fileId, ?string $identifyMethod, ?string $signMethod, ?string $identify): DataResponse {
319+
public function requestCodeByFileId(int $fileId, ?string $identifyMethod, ?string $signMethod, ?string $identify): DataResponse {
314320
try {
315321
$signRequest = $this->signRequestMapper->getByFileIdAndUserId($fileId);
316322
} catch (\Throwable) {

‎lib/Controller/SignatureElementsController.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ public function getSignatureElements(): DataResponse {
161161
#[NoCSRFRequired]
162162
#[RequireSignRequestUuid(skipIfAuthenticated: true)]
163163
#[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/signature/elements/preview/{nodeId}', requirements: ['apiVersion' => '(v1)'])]
164-
public function getSignatureElementPreview(int $nodeId) {
164+
public function previewSignatureElement(int $nodeId) {
165165
try {
166166
$node = $this->accountService->getFileByNodeId($nodeId);
167167
if ($this->preview->isAvailable($node)) {

0 commit comments

Comments
 (0)