-
Notifications
You must be signed in to change notification settings - Fork 3
/
swagger.yaml
1211 lines (1211 loc) · 54 KB
/
swagger.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
swagger: '2.0'
info:
description: '<p>The component is based on tf-idf numerical statistics. The aim of the API is to calculate the similarity score between multiple pairs of requirements.</p><p>There are three types of operations (each method has a more extensive description in its own operation box): </p><ul><li><strong>Similarity without clusters</strong>: These methods work only with a set of input requirements. There are two types of operations. The ones that generate and update a tf-idf model with the input requirements, and the ones that use these tf-idf models to compute the similarity between the requirements; therefore, before using the operations, is necessary to create a tf-idf model first for the organization. Each tf-idf model is assigned to an organization and can be used infinite times. </li><ul><li>BuildModel: Pre-processes the input requirements, generates a tf-idf model and assings it to an specified organization.</li><li>BuildModelAndCompute: Pre-processes the input requirements, generates a tf-idf model with the input requirements and computes and returns the similarity score between all the possible pairs of requirements.</li><li>AddRequirements: Pre-processes the input requirements and adds them to an existing tf-idf model.</li><li>DeleteRequirements: Deletes the input requirements from an existing tf-idf model.</li><li>ReqReq: Compares two requirements.</li><li>ReqProject: Compares all the requirements in the input list with a set of requirements given in the input.</li><li>Project: Compares all possible pairs of requirements of an organization.</li><li>ProjectProject: Compares each requirement of a project with all the requirements of another project.</li><li>ReqOrganization: Compares a set of requirements with all the requirements of an organization.</li><li>NewReqOrganization: Pre-processes the input requirements and adds them to an organization''s tf-idf model. It also compares the input requirements with all the requirements of the organization.</li></ul><li><strong>Similarity with clusters</strong>: These methods work with a set of input requirements and dependencies. <u>The clusters are considered as graphs connected by similarity dependencies accepted by the user where the nodes are the requirements of the model</u>. We denominate orphans to the clusters with only one requirement. </li><ul><li>BuildClusters: Pre-processes the input requirements, generates a tf-idf model with the requirements information, the clusters architecture and the input similarity dependencies and assigns it to an specified organization. All the requirements are compared with all the requirements of other clusters of the organization, and the maximum score with each cluster for each requirement is stored in the database.</li><li>BuildClustersAndCompute: Pre-processes the input requirements, generates a tf-idf model with the requirements information, the clusters architecture and the input similarity dependencies and assings it to an specified organization. All the requirements are compared with all the requirements of other clusters of the organization, and the maximum score with each cluster for each requirement is stored in the database. The method returns the maximum similarity score between each requirement and all the requirements that make up each one of the existing clusters of the organization.</li><li>ReqClusters: Given a list of requirements ids, returns the maximum similarity score between each requirement and all the requirements that make up each of the existing clusters in the organization model.</li><li>BatchProcess: Given a set of updates done in the requirements, updates the clusters and dependencies accordingly.</li><li>TreatAcceptedAndRejectedDependencies: Given a set of accepted and rejected dependencies, updates the clusters and dependencies accordingly.</li></ul><li><strong>Auxiliary methods</strong>:</li><ul><li>GetResponse: Returns the output of the async methods</li><li>GetOrganizationInfo: Returns the main information of the specified organization including the current computations and the pending responses</li><li>DeleteOrganizationResponses: Deletes the organization responses from the database</li><li>ClearDatabase: Deletes all data from the database</li></ul></ul><p>All operations except <i>ReqReq</i>, <i>ReqClusters</i>, <i>TreatAcceptedAndRejectedDependencies</i> and the auxiliary methods are asynchronous. All these operations follow the same pattern:</p><ol><li>The client calls the operation with all necessary parameters</li><li>The service receives the request and checks the main conditions</li><li>The service returns if the client request has been accepted or not and closes the connection<ul><li>(httpStatus!=200) The request has not been accepted. The message body contains the exception cause.</li><li>(httpStatus==200) The request has been accepted. The similarity calculation runs in the background. The message body contains the request identifier, i.e., <em>{"id": "1548924677975_523"}</em></li></ul><li>When the calculation finishes (only if the request has been accepted) the service opens a connection with the server url specified as parameter (optional). It sends a JSON object that contains the outcome of the computation:<br><ul><li>(success) Example: {"code": 200,"id": "1557395889689_587","operation": "AddReqs"}.</li><li>(!success) Example: {"code": 400,"id": "1557396039530_583","error": "Bad request","message": "The requirement with id QM-3 is already inside the project","operation": "ReqProject"}.</li></ul><li>The result of the operation can be obtained through the GetResponse method.</li></li></ol><p>The service uses locks to control the concurrency of the different operations in each organization. To guarantee the ACID properties the methods which write or update data can''t be parallelized. For example, the BuildClusters and BatchProcess methods cannot be parallelized, one has to wait for the other before starting. The service has a small queue of about 5 minutes to solve the small deviations. However, if one method has to wait for more than 5 minutes it will return an error with code 423. This only happens with methods using the same organization. The methods like ReqClusters that only read data from the database are not affected.</p><p>The API uses UTF-8 charset. Also, it uses the OpenReq format for input JSONs (it is specified in the Models section).</p>'
version: '3.3'
title: SIMILARITY DETECTION COMPONENT
contact:
name: UPC-GESSI (OPENReq)
url: 'http://openreq.eu/'
license:
name: License
url: 'https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt'
host: api.openreq.eu
basePath: /similarity-detection
tags:
- name: rest-api-controller
description: Rest Api Controller
schemes:
- https
paths:
/upc/similarity-detection/AddRequirements:
post:
tags:
- Similarity without clusters
summary: Adds requirements to the tf-idf model of an organization.
description: |-
<p><i>Asynchronous</i> method.</p><p>Given a list of requirements, the endpoint pre-processes them and adds them to a specified organization’s tf-idf model. If some of the entry requirements were already part of the model, the endpoint will update its information.
</p>
operationId: addRequirementsUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: input
description: OpenReq JSON with requirements
required: true
schema:
$ref: '#/definitions/Requirements'
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/BatchProcess:
post:
tags:
- Similarity with clusters
summary: Updates the organization clusters with the input requirements and dependencies.
description: '<p><i>Asynchronous</i> method.</p><p>Given a set of updates done in the requirements (see next list), updates the clusters accordingly (the <i>created_at</i> and <i>modified_at</i> params are taken into account).</p><p><ul><li>Adds requirements: The input requirements that do not pertain to the organization''s model are considered to be new requirements. The method stores the pre-processing of the new requirements, adds them to the tf-idf model, and puts the new requirements as clusters of one requirement.</li><li>Deletes requirements: The input requirements with status equal to deleted that pertain to the organization''s model are considered to be deleted requirements. The method deletes them from the organization models.</li><li>Updates requirements: The input requirements with a title or text different from the one stored in the database are considered updated requirements. The method updates their pre-processing in the database and updates the organization clusters accordingly.</li><li>Adds dependencies: The input similarity dependencies that do not pertain to the organization''s model are considered to be new dependencies. The method uses the accepted and rejected dependencies to update the organization clusters.</li><li>Deletes dependencies: The input similarity dependencies with status equal to deleted that do pertain to the organization''s model are considered to be deleted dependencies. The method deletes any status or rejected dependency between the same requirements from inside the organization models.</li></ul></p>'
operationId: batchProcessUsingPOST
consumes:
- application/json
produces:
- '*/*'
parameters:
- in: body
name: input
description: OpenReq JSON with requirements and dependencies
required: true
schema:
$ref: '#/definitions/RequirementsAndDependencies'
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/BuildClusters:
post:
tags:
- Similarity with clusters
summary: Generates the clusters using the input requirements and dependencies.
description: '<p><i>Asynchronous</i> method.</p><p>This method computes the clusters using the existing duplicates. These duplicates relations are defined by the dependencies with type equal to <i>similar</i> or <i>duplicates</i> and status equal to <i>accepted</i>, <i>rejected</i> or <i>deleted</i> (the <i>created_at</i> and <i>modified_at</i> params are taken into account). All the requirements that do not have duplicates relationships with other requirements are considered to be in a cluster of just one requirement. All the requirements are pre-processed and stored in the database, together with their corresponding tf-idf model and the clusters information. The user can choose whether to use only the name of the requirements for constructing the tf-idf model, or to use also the text of the requirements. Also the user can choose whether to use the requirement component in the similarity step (the score between two requirements with different components and not null will be decreased). Finally, all the requirements are compared with all the requirements of other clusters of the organization, and those similarities with score greater than the established threshold for each requirement are stored in the database.</p><br><p>Each organization can only have one model at the same time. The service throws a forbidden exception if at the time of generating a new model the corresponding organization already has an existing one</p>'
operationId: buildClustersUsingPOST
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: compare
in: query
description: Use the text field of the requirements to construct the model
required: false
type: boolean
allowEmptyValue: false
x-example: true
- name: file
in: formData
description: OpenReq JSON with requirements and dependencies
required: true
type: file
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the proposed dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
- name: useComponent
in: query
description: Use the component attribute in the similarity comparison
required: false
type: boolean
allowEmptyValue: false
x-example: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/BuildClustersAndCompute:
post:
tags:
- Similarity with clusters
summary: 'Generates the clusters using the input requirements and dependencies, and returns the similarity score between them.'
description: '<p><i>Asynchronous</i> method.</p><p>This method computes the clusters using the existing duplicates. These duplicates relations are defined by the dependencies with type equal to <i>similar</i> or <i>duplicates</i> and type equal to <i>accepted</i>, <i>rejected</i> or <i>deleted</i> (the <i>created_at</i> and <i>modified_at</i> params are taken into account). All the requirements that do not have duplicates relationships with other requirements are considered to be in a cluster of just one requirement. All the requirements are pre-processed and stored in the database, together with their corresponding tf-idf model and the clusters information. The user can choose whether to use only the name of the requirements for constructing the tf-idf model, or to use also the text of the requirements. Also the user can choose whether to use the requirement component in the similarity step (the score between two requirements with different components and not null will be decreased). Finally, all the requirements are compared with all the requirements of other clusters of the organization, and those similarities with score greater than the established threshold for each requirement are stored in the database. It returns for each requirement the highest similarity score for each cluster (only if they are greater than the established threshold). If the number of maximum dependencies to be returned is received as parameter (maxNumber), the method only returns the <i>maxNumber</i> of dependencies with highest score for each requirement. When <i>maxNumber</i> is equal to 0 only the accepted dependencies are returned and when maxNumber is lower than 0 or not specified, all the accepted and proposed dependencies of each requirement are returned.</p><br><p>Each organization can only have one model at the same time. The service throws a forbidden exception if at the time of generating a new model the corresponding organization already has an existing one</p>'
operationId: buildClustersAndComputeUsingPOST
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: compare
in: query
description: Use the text field of the requirements to construct the model
required: false
type: boolean
allowEmptyValue: false
x-example: true
- name: file
in: formData
description: OpenReq JSON with requirements and dependencies
required: true
type: file
- name: maxNumber
in: query
description: Max number of dependencies to return for each requirement
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 10
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the proposed dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
- name: useComponent
in: query
description: Use the component attribute in the similarity comparison
required: false
type: boolean
allowEmptyValue: false
x-example: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/BuildModel:
post:
tags:
- Similarity without clusters
summary: Builds a tf-idf model with the input requirements.
description: '<p><i>Asynchronous</i> method.</p><p>Builds a tf-idf model with the requirements specified in the JSON object. The generated model is assigned to the specified organization and stored in an internal database. Each organization only can have one model. The service throws a forbidden exception if at the time of generating a new model the corresponding organization already has an existing one. The user can choose whether to use only the name of the requirements for constructing the model, or to use also the text of the requirements. Also the user can choose whether to use the requirement component in the similarity step (the score between two requirements with different components and not null will be decreased).</p>'
operationId: buildModelUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: compare
in: query
description: Use the text field of the requirements to construct the model
required: false
type: boolean
allowEmptyValue: false
x-example: true
- in: body
name: input
description: OpenReq JSON with requirements
required: true
schema:
$ref: '#/definitions/Requirements'
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
- name: useComponent
in: query
description: Use the component attribute in the similarity comparison
required: false
type: boolean
allowEmptyValue: false
x-example: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/BuildModelAndCompute:
post:
tags:
- Similarity without clusters
summary: Builds a tf-idf model with the input requirements and returns the similarity scores among all the possible pairs of requirements.
description: '<p><i>Asynchronous</i> method.</p><p>Builds a tf-idf model with the requirements specified in the JSON object.The generated model is assigned to the specified organization and stored in an internal database. Each organization only can have one model. The service throws a forbidden exception if at the time of generating a new model the corresponding organization already has an existing one. The user can choose whether to use only the name of the requirements for constructing the model, or to use also the text of the requirements. Also the user can choose whether to use the requirement component in the similarity step (the score between two requirements with different components and not null will be decreased).</p><br><p>This method returns an array of dependencies containing the similarities that are greater than the established threshold between all possible pairs of requirements received as input. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: buildModelAndComputeUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: compare
in: query
description: Use the text field of the requirements to construct the model
required: false
type: boolean
allowEmptyValue: false
x-example: true
- in: body
name: input
description: OpenReq JSON with requirements
required: true
schema:
$ref: '#/definitions/Requirements'
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
- name: useComponent
in: query
description: Use the component attribute in the similarity comparison
required: false
type: boolean
allowEmptyValue: false
x-example: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ClearDatabase:
delete:
tags:
- Auxiliary methods
summary: Clears all data from the database.
description: '<p><i>Synchronous</i> method.</p><p>Clears all data from the database. If this method is called while a calculation is being carried out, unforeseen results may occur.</p>'
operationId: clearDatabaseUsingDELETE
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/DeleteOrganizationData:
delete:
tags:
- Auxiliary methods
summary: Deletes the organization's requirements data.
description: '<p><i>Synchronous</i> method.</p><p>Deletes all the models data (tf-idf and/or clusters) of the specified organization. If this method is called while a calculation is being carried out with the chosen organization, unforeseen results may occur.</p>'
operationId: clearOrganizationUsingDELETE
produces:
- application/json
parameters:
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/DeleteOrganizationResponses:
delete:
tags:
- Auxiliary methods
summary: 'Deletes the organization''s responses. '
description: '<p><i>Synchronous</i> method.</p><p>Deletes the organization responses that are finished (i.e., their computation is finished) from the database.</p>'
operationId: deleteOrganizationResponsesUsingDELETE
produces:
- application/json
parameters:
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/DeleteRequirements:
post:
tags:
- Similarity without clusters
summary: Deletes requirements from the tf-idf model of an organization
description: |-
<p><i>Asynchronous</i> method.</p><p>Given a list of requirements, the endpoint deletes them from a specified organization’s tf-idf model.
</p>
operationId: deleteRequirementsUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: input
description: OpenReq JSON with requirements
required: true
schema:
$ref: '#/definitions/Requirements'
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/GetOrganizationInfo:
get:
tags:
- Auxiliary methods
summary: Returns the main organization information
description: '<p><i>Synchronous</i> method.</p>Returns the main information of the specified organization (name, threshold, if it uses the text attribute and if it has clusters). Also the method returns the async operations that have not finished yet and the pending responses to read.<p></p>'
operationId: getOrganizationInfoUsingGET
produces:
- application/json
parameters:
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/GetResponse:
get:
tags:
- Auxiliary methods
summary: Returns the dependencies that are the result of the other operations.
description: '<p><i>Synchronous</i> method.</p><p>Returns the result JSON of the asynchronous methods of this API (i.e., all the methods except <i>ReqReq</i>, <i>ReqClusters</i>, <i>TreatAcceptedAndRejectedDependencies</i> and the auxiliary methods). The result is a JSON object formed by a status attribute. If the status is 200 the JSON also contains an array of dependencies which are returned in batches of 20,000 . Each time this operation is called, the following 20,000 dependencies of the indicated response will be returned. An empty JSON will be returned when no more dependencies are left. Nevertheless, if the status attribute is not equal to 200, the json contains the exception message. </p>'
operationId: getResponsePageUsingGET
produces:
- application/json
parameters:
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: response
in: query
description: Response identifier
required: true
type: string
allowEmptyValue: false
x-example: '12345678_89'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'404':
description: Not found
'423':
description: The computation is not finished yet
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/NewReqOrganization:
post:
tags:
- Similarity without clusters
summary: 'Similarity comparison between a set of input requirements and all the requirements of the specified organization. '
description: '<p><i>Asynchronous</i> method.</p><p>Adds the input requirements to the organization''s tf-idf model and returns an array of similarity dependencies with a score above the specified threshold between them and all the requirements of the specified organization Also the requirements of the input list are compared between each other. If any input requirement is already part of the organization''s model, it will be overwritten with the new information. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: simNewReqOrganizationUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: input
description: OpenReq JSON with the requirements to compare
required: true
schema:
$ref: '#/definitions/Requirements'
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/Project:
post:
tags:
- Similarity without clusters
summary: Similarity comparison between the requirements of one project.
description: '<p><i>Asynchronous</i> method.</p><p>Returns an array of similarity dependencies with a score above the specified threshold between all possible pairs of requirements from the project received as input. The similarity score is computed with the tf-idf model assigned to the specified organization. The input ids that do not belong to any organization requirement are ignored. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: simProjectUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: input
description: OpenReq JSON with the project specifying the id of the requirements the project has
required: true
schema:
$ref: '#/definitions/Projects'
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: project
in: query
description: Id of the project to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-P1
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ProjectProject:
post:
tags:
- Similarity without clusters
summary: Similarity comparison between two projects.
description: '<p><i>Asynchronous</i> method.</p><p>Returns an array of similarity dependencies with a score above the specified threshold between each requirement of the first project and all the requirements of the second one. The similarity score is computed with the tf-idf model assigned to the indicated organization. The input ids that do not belong to any organization requirement are ignored. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: simProjectProjectUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: firstProject
in: query
description: Id of the first project to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-P1
- in: body
name: input
description: OpenReq JSON with the input projects and their requirements
required: true
schema:
$ref: '#/definitions/Projects'
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: secondProject
in: query
description: Id of the second project to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-P2
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ReqClusters:
post:
tags:
- Similarity with clusters
summary: Similarity comparison between a requirement and all the organization's clusters.
description: '<p><i>Synchronous</i> method.</p><p>The requirements received should already exist for the organization and should have already been preprocessed; the method only needs the id of the requirement (received as a parameter). It returns a dependencies array with the highest similarity comparison between each input requirement and all the requirements of each cluster (it returns both accepted and proposed dependencies, but not the rejected ones). The comparisons are done with all the requirements (i.e.m clusters) in the database for this organization. If the number of maximum dependencies to be returned is received as parameter (maxNumber), the method only returns the <i>maxNumber</i> of dependencies with highest score. When <i>maxNumber</i> is equal to 0 only the accepted dependencies are returned and when maxNumber is lower than 0 or not specified, all the accepted and proposed dependencies of the requirement received as input are returned.</p>'
operationId: simReqClustersUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 10
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: requirementId
in: query
description: Requirement id
required: true
type: string
allowEmptyValue: false
x-example: UPC-1
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ReqOrganization:
post:
tags:
- Similarity without clusters
summary: 'Similarity comparison between a set of requirements and all the requirements of the specified organization. '
description: '<p><i>Asynchronous</i> method.</p><p>Compares the existing organization''s requirements that appear in the input array of ids with all the organization''s requirements. Returns an array with all the similarity dependencies that are above the specified threshold. The input ids that do not belong to the requirements of the organization are ignored. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: simReqOrganizationUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: req
in: query
description: Id of the requirements to compare
required: true
type: array
items:
type: string
collectionFormat: multi
allowEmptyValue: false
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ReqProject:
post:
tags:
- Similarity without clusters
summary: Similarity comparison between a list of requirements and all the requirements of an specific project.
description: '<p><i>Asynchronous</i> method.</p><p>Returns an array of similarity dependencies with a score above the specified threshold between the list of requirements and the project''s requirements received as input. Also the requirements of the input list are compared between each other. The similarity score is computed with the tf-idf model assigned to the specified organization. The input ids that do not belong to any organization requirement are ignored. The method can be set to return the dependencies with the higher score thanks to the parameter named maxNumber (with a negative number or a zero in this parameter, the method works as explained before).</p>'
operationId: simReqProjectUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: input
description: OpenReq JSON with the project
required: true
schema:
$ref: '#/definitions/Projects'
- name: maxNumber
in: query
description: Max number of dependencies to return
required: false
type: integer
format: int32
allowEmptyValue: false
x-example: 0
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: project
in: query
description: Id of the project to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-P1
- name: req
in: query
description: Id of the requirements to compare
required: true
type: array
items:
type: string
collectionFormat: multi
allowEmptyValue: false
- name: threshold
in: query
description: Double between 0 and 1 that establishes the minimum similarity score that the added dependencies should have
required: true
type: number
format: double
allowEmptyValue: false
x-example: 0.1
- name: url
in: query
description: The url where the result of the operation will be returned
required: false
type: string
allowEmptyValue: false
x-example: 'http://localhost:9406/upload/PostResult'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'400':
description: Bad request
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/ReqReq:
post:
tags:
- Similarity without clusters
summary: 'Similarity comparison between two requirements. '
description: <p><i>Synchronous</i> method.</p><p>Returns a dependency between the two input requirements. The similarity score is computed with the tf-idf model assigned to the specified organization. The two requirements must be in this model.</p>
operationId: simReqReqUsingPOST
consumes:
- application/json
produces:
- application/json
parameters:
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
- name: req1
in: query
description: Id of the first requirement to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-98
- name: req2
in: query
description: Id of the second requirement to compare
required: true
type: string
allowEmptyValue: false
x-example: UPC-97
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ResponseEntity'
'404':
description: Not found
'500':
description: Internal error
deprecated: false
/upc/similarity-detection/TreatAcceptedAndRejectedDependencies:
post:
tags:
- Similarity with clusters
summary: Updates the organization clusters with the input dependencies.
description: '<p><i>Synchronous</i> method.</p><p>Given a set of <i>accepted</i>, <i>rejected</i> and <i>deleted</i> dependencies, updates the clusters and dependencies accordingly. The method takes into account the params <i>created_at</i> and <i>modified_at</i>.</p>'
operationId: treatAcceptedAndRejectedDependenciesUsingPOST
consumes:
- application/json
produces:
- '*/*'
parameters:
- in: body
name: input
description: OpenReqJson with dependencies
required: true
schema:
$ref: '#/definitions/Dependencies'
- name: organization
in: query
description: Organization
required: true
type: string
allowEmptyValue: false
x-example: UPC
responses: