Cleanup of descriptions in endpoints files

The OpenAPI `endpoints` files included a number of leftover or potentially misleading descripions, e.g.: * "get a list of..." as description for responses, although responses depend on granularity and delivered in different Beacon response schemas * frequent use of "variant" instead "variation" * some wrong labels (e.g. C&P errors or leftover "examples" response) Additionally the leftover commented lines from the yamlerRunner have been removed.
ga4gh-beacon · Jul 17, 2024 · a6fe8ad · a6fe8ad
1 parent f6f85c4
commit a6fe8ad
Show file tree

Hide file tree

Showing 15 changed files with 181 additions and 159 deletions.
diff --git a/bin/yamlerRunner.sh b/bin/yamlerRunner.sh
@@ -1,28 +1,13 @@
 BASEDIR=$(dirname $0)
 UNITYPATH=$BASEDIR/..
-
-# initial conversion from separate schemas
-# DEPRECATED
-# BEACONMODELPATH=$BASEDIR/../../beacon-v2-Models/BEACON-V2-Model
-# BEACONFRAMEWORKPATH=$BASEDIR/../../beacon-framework-v2
-
 BEACONMODELNAME=beacon-v2-default-model
 
-# for UPSTREAM in $BEACONMODELPATH $BEACONFRAMEWORKPATH
-# do
-# 	echo "pulling $UPSTREAM"
-# 	git -C $UPSTREAM pull
-# done
-
 for KIND in src json
 do
 	mkdir -p $UNITYPATH/models/$KIND/$BEACONMODELNAME
 	mkdir -p $UNITYPATH/framework/$KIND	
 done
 
-# $BASEDIR/beaconYamler.py -i $BEACONMODELPATH -t json -x yaml -o $UNITYPATH/models/src/$BEACONMODELNAME
-# $BASEDIR/beaconYamler.py -i $BEACONFRAMEWORKPATH -t json -x yaml -o $UNITYPATH/framework/src
-
 # recurring conversion from the source files to the exported versions
 $BASEDIR/beaconYamler.py -i $UNITYPATH/models/src/$BEACONMODELNAME -t yaml -x json -o $UNITYPATH/models/json/$BEACONMODELNAME
 $BASEDIR/beaconYamler.py -i $UNITYPATH/framework/src -t yaml -x json -o $UNITYPATH/framework/json
diff --git a/models/json/beacon-v2-default-model/analyses/endpoints.json b/models/json/beacon-v2-default-model/analyses/endpoints.json
@@ -91,7 +91,7 @@
     "paths": {
         "/analyses": {
             "get": {
-                "description": "Get a list of bioinformatics analysis",
+                "description": "Get a Beacon response for bioinformatics analyses",
                 "operationId": "getAnalyses",
                 "parameters": [
                     {
@@ -123,7 +123,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of bioinformatics analysis",
+                "description": "Get a Beacon response for bioinformatics analyses",
                 "operationId": "postAnalysesRequest",
                 "requestBody": {
                     "content": {
@@ -207,8 +207,8 @@
         },
         "/analyses/{id}/g_variants": {
             "get": {
-                "description": "Get the list of variants instances for one bioinformatics analysis, identified by its (unique) 'id'",
-                "operationId": "getOneAnalysisVariants",
+                "description": "Get a *genomic variations* response for one bioinformatics analysis, identified by its (unique) 'id'",
+                "operationId": "getOneAnalysisVariationsRequest",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -239,8 +239,8 @@
                 }
             ],
             "post": {
-                "description": "Get the list of variants instances for one bioinformatics analysis, identified by its (unique) 'id'",
-                "operationId": "postOneAnalysisVariantsRequest",
+                "description": "Get a *genomic variations* response for one bioinformatics analysis, identified by its (unique) 'id'",
+                "operationId": "postOneAnalysisVariationsRequest",
                 "requestBody": {
                     "content": {
                         "application/json": {

diff --git a/models/json/beacon-v2-default-model/biosamples/endpoints.json b/models/json/beacon-v2-default-model/biosamples/endpoints.json
@@ -95,7 +95,7 @@
     "paths": {
         "/biosamples": {
             "get": {
-                "description": "Get a list of biosamples",
+                "description": "Get a Beacon response for biosamples",
                 "operationId": "getBiosamples",
                 "parameters": [
                     {
@@ -127,7 +127,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of biosamples",
+                "description": "Get a Beacon response for biosamples",
                 "operationId": "postBiosamplesRequest",
                 "requestBody": {
                     "content": {
@@ -204,8 +204,8 @@
         },
         "/biosamples/{id}/analyses": {
             "get": {
-                "description": "Get the analysis list from one biosample, identified by its (unique) 'id'",
-                "operationId": "getOneBiosampleAnalysis",
+                "description": "Get an *analyses* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "getOneBiosampleAnalyses",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -236,8 +236,8 @@
                 }
             ],
             "post": {
-                "description": "Get the analysis list from one biosample, identified by its (unique) 'id'",
-                "operationId": "postOneBiosampleAnalysis",
+                "description": "Get an *analyses* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "postOneBiosampleAnalyses",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -264,8 +264,8 @@
         },
         "/biosamples/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one biosample, identified by its (unique) 'id'",
-                "operationId": "getOneBiosampleGenomicVariants",
+                "description": "Get a *genomic variations* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "getOneBiosampleGenomicVariations",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -296,8 +296,8 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one biosample, identified by its (unique) 'id'",
-                "operationId": "postOneBiosampleGenomicVariants",
+                "description": "Get a *genomic variations* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "postOneBiosampleGenomicVariations",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -324,7 +324,7 @@
         },
         "/biosamples/{id}/runs": {
             "get": {
-                "description": "Get the runs list from one biosample, identified by its (unique) 'id'",
+                "description": "Get a *runs* response from one biosample, identified by its (unique) 'id'",
                 "operationId": "getOneBiosampleRuns",
                 "parameters": [
                     {
@@ -363,7 +363,7 @@
                 }
             ],
             "post": {
-                "description": "Get the runs list from one biosample, identified by its (unique) 'id'",
+                "description": "Get a *runs* response from one biosample, identified by its (unique) 'id'",
                 "operationId": "postOneBiosampleRuns",
                 "requestBody": {
                     "content": {

diff --git a/models/json/beacon-v2-default-model/cohorts/endpoints.json b/models/json/beacon-v2-default-model/cohorts/endpoints.json
@@ -108,7 +108,7 @@
     "paths": {
         "/cohorts": {
             "get": {
-                "description": "Get a list of cohorts",
+                "description": "Get a Beacon *cohorts* response",
                 "operationId": "getCohorts",
                 "parameters": [
                     {
@@ -137,7 +137,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of cohorts",
+                "description": "Get a Beacon *cohorts* response",
                 "operationId": "postCohortsRequest",
                 "requestBody": {
                     "content": {
@@ -219,7 +219,7 @@
         },
         "/cohorts/{id}/filtering_terms": {
             "get": {
-                "description": "Get the list of filtering terms that could be used with a given cohort, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given cohort, identified by its (unique) 'id'",
                 "operationId": "getOneCohortFilteringTerms",
                 "parameters": [
                     {
@@ -255,7 +255,7 @@
                 }
             ],
             "post": {
-                "description": "Get the list of filtering terms that could be used with a given cohort, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given cohort, identified by its (unique) 'id'",
                 "operationId": "postOneCohortFilteringTerms",
                 "requestBody": {
                     "content": {
@@ -290,7 +290,7 @@
         },
         "/cohorts/{id}/individuals": {
             "get": {
-                "description": "Get the individuals from one cohort, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one cohort, identified by its (unique) 'id'",
                 "operationId": "getOneCohortIndividuals",
                 "parameters": [
                     {
@@ -322,7 +322,7 @@
                 }
             ],
             "post": {
-                "description": "Get the individuals from one cohort, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one cohort, identified by its (unique) 'id'",
                 "operationId": "postOneCohortEntries",
                 "requestBody": {
                     "content": {

diff --git a/models/json/beacon-v2-default-model/datasets/endpoints.json b/models/json/beacon-v2-default-model/datasets/endpoints.json
@@ -135,7 +135,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of datasets",
+                "description": "Get a Beacon *datasets* response",
                 "operationId": "postDatasetsRequest",
                 "requestBody": {
                     "content": {
@@ -217,7 +217,7 @@
         },
         "/datasets/{id}/biosamples": {
             "get": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetBiosamples",
                 "parameters": [
                     {
@@ -249,7 +249,7 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetBiosamples",
                 "requestBody": {
                     "content": {
@@ -277,7 +277,7 @@
         },
         "/datasets/{id}/filtering_terms": {
             "get": {
-                "description": "Get the list of filtering terms that could be used with a given dataset, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetFilteringTerms",
                 "parameters": [
                     {
@@ -313,7 +313,7 @@
                 }
             ],
             "post": {
-                "description": "Get the list of filtering terms that could be used with a given dataset, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetFilteringTerms",
                 "requestBody": {
                     "content": {
@@ -348,7 +348,7 @@
         },
         "/datasets/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetEntries",
                 "parameters": [
                     {
@@ -380,7 +380,7 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetEntries",
                 "requestBody": {
                     "content": {
@@ -408,7 +408,7 @@
         },
         "/datasets/{id}/individuals": {
             "get": {
-                "description": "Get the individuals list from one dataset, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetIndividuals",
                 "parameters": [
                     {
@@ -440,7 +440,7 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetIndividuals",
                 "requestBody": {
                     "content": {

diff --git a/models/json/beacon-v2-default-model/genomicVariations/endpoints.json b/models/json/beacon-v2-default-model/genomicVariations/endpoints.json
@@ -193,8 +193,8 @@
     "paths": {
         "/g_variants": {
             "get": {
-                "description": "Get a list of example entries",
-                "operationId": "getExampleEntries",
+                "description": "Get a Beacon response for genomic variations",
+                "operationId": "getGenomicVariations",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -258,8 +258,8 @@
                 ]
             },
             "post": {
-                "description": "Get a list of example entries",
-                "operationId": "postExampleEntriesRequest",
+                "description": "Get a Beacon response for genomic variations",
+                "operationId": "postGenomicVariationsRequest",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -335,8 +335,8 @@
         },
         "/g_variants/{id}/biosamples": {
             "get": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "getOneGenomicVariantBiosamples",
+                "description": "Get a *biosamples* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "getOneGenomicVariationBiosamples",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -367,8 +367,8 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "postOneGenomicVariantBiosamples",
+                "description": "Get a *biosamples* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "postOneGenomicVariationBiosamples",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -395,8 +395,8 @@
         },
         "/g_variants/{id}/individuals": {
             "get": {
-                "description": "Get the individuals list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "getOneGenomicVariantIndividuals",
+                "description": "Get an *individuals* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "getOneGenomicVariationIndividuals",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -427,8 +427,8 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "postOneGenomicVariantIndividuals",
+                "description": "Get an *individuals* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "postOneGenomicVariationIndividuals",
                 "requestBody": {
                     "content": {
                         "application/json": {