docs: content quality checks

Signed-off-by: Artemis Lavasa <[email protected]>

Author: ArtemisLav

spec/components/securitySchemes/Access Token.yaml

@@ -2,11 +2,11 @@ type: apiKey
 in: query
 name: access_token
 description: >
-  > Your access token will allow you to use the service in the same way in which
-  you may use it if you log in on the web portal. You will have the same
-  permissions unless specified otherwise creation of the token. This implies
+  > Your access token will allow you to use the service in the same way you would
+  use it through the web portal. You will have the same
+  permissions unless specified otherwise during the creation of the token. This implies
   that anyone who has this token can log in as yourself to the service. Do not
-  share your personal access token with anyone else, and only use it with HTTPS!
+  share your personal access token with anyone else, and only use it with HTTPS.
 
 
   To get an access token, you will need to log in on the web portal and [create

spec/openapi.yaml

@@ -2,26 +2,24 @@ openapi: 3.0.0
 info:
   version: 1.0.0
   title: CERN Analysis Preservation REST API
-  termsOfService: 'https://analysispreservation.cern.ch/terms/'
   contact:
     email: [email protected]
-    url: 'https://analysispreservation.cern.ch/about'
-  license:
-    name: Apache 2.0
-    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+    url: 'https://analysispreservation.cern.ch'
   x-logo:
     url: >-
       https://github.com/cernanalysispreservation/cap-api-docs/raw/master/web/CAP_API_docs.png
   description: >
+
+    CERN Analysis Preservation (CAP) is a service developed at the European Organization for Nuclear Research (CERN) to support researchers in preserving and documenting the various components of their physics analyses, so that they are reusable and understandable in the future.
+
     CERN Analysis Preservation offers a REST API to access the service
     independently from the web interface. This allows users to automate specific
     tasks or create their own data interface, using simple HTTP calls.
 
 
     # Introduction
 
-    CERN Analysis Preservation provides a RESTful API, built on HTTP. It tries
-    to provide a predictable interface, that includes:
+    CERN Analysis Preservation provides a RESTful API, built on HTTP. It provides a predictable interface, that includes:
 
     * resource URLs,
 
@@ -33,8 +31,8 @@ info:
     You can use your favorite HTTP/REST library for your programming language to
     use CAP's API, or you can use one of our SDKs (CLI clients), currently
     available in Python. Every action from our app is implemented using REST
-    endpoints, all of which are documented and available, in order to bea easily
-    accessible for automations and integrations into specific workflowsor
+    endpoints, all of which are documented and available, in order to be easily
+    accessible for automations and integrations into specific workflows or
     data-related apps.
 
 
@@ -54,21 +52,21 @@ info:
 
     <!-- ReDoc-Inject: <security-definitions> -->
 externalDocs:
-  description: Click here if you are looking for our developement documentation.
+  description: Click here if you are looking for our development documentation.
   url: 'https://cernanalysispreservation.readthedocs.io'
 tags:
   - name: Deposits
-    description: The Deposit resource is used for uploading and editing records on CAP
+    description: The Deposit resource is used for uploading and editing records on CAP.
   - name: Records
     description: >
       The Record resource is used for fetching and searching published records
       on CAP. Create deposit
   - name: Files
     description: >
-      The Files resource is used for uploading files and attach them to
-      records/deposits
+      The Files resource is used for uploading files and attachinging them to
+      records/deposits.
 
-      The following type of upload are possible:
+      The following types of uploads are possible:
         * Local files
         * Git repos
         * URL linked files
@@ -81,7 +79,7 @@ tags:
   - name: Services
     description: Operations about services
   - name: User
-    description: Operations about user
+    description: Operations about users
 security:
   - Access Token: []
 servers:

spec/paths/deposits.yaml

@@ -6,12 +6,10 @@ post:
 
 
     > JSON Schemas and analysis types (`$ana_type`) depend on the access rights
-    you have and mainly\
-
-    correspond to the CERN collaboration you are part of (***ALICE, ATLAS, CMS,
+    you have and mainly correspond to the CERN collaboration you are part of (***ALICE, ATLAS, CMS,
     LHCb***).\
 
-    To get the list of available schemas you can call the 
+    To get the list of available schemas you can call the
   tags:
     - Deposits
   requestBody:
@@ -59,8 +57,8 @@ post:
 get:
   summary: List all deposits/drafts
   description: >-
-    List all deposits for the currently authenticated user. At least `read`
-    access is needed to query a record
+    List all deposits for the currently authenticated user.
+    > At least `read` access is needed to query a record.
   tags:
     - Deposits
   parameters:

spec/paths/deposits@{depid}.yaml

@@ -11,8 +11,8 @@ get:
     - Deposits
   summary: Get deposit by ID
   description: |
-    Retrieve a deposit/draft resource by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a deposit/draft resource using `deposit_id`.
+    > You need to have at least 'read' access.
   operationId: get_deposit
   responses:
     '200':
@@ -34,7 +34,7 @@ put:
   tags:
     - Deposits
   summary: Update a deposit
-  description: Update a deposit/draft resource
+  description: Update a deposit/draft resource.
   operationId: depositUpdate
   requestBody:
     content:
@@ -45,8 +45,8 @@ put:
           title: My new title
           abstract: Already commited/saved abstract desciption
     description: |
-      A JSON object that will replace the `metadata` field of the resource
-      > It should validate against the specified `$schema` of the resource
+      A JSON object that will replace the `metadata` field of the resource.
+      > It should validate against the specified `$schema` of the resource.
     required: true
   responses:
     '200':
@@ -70,7 +70,7 @@ patch:
     - Deposits
   summary: Patch a deposit
   description: >
-    Update a deposit/draft resource with a [JSON Patch](http://jsonpatch.com/)
+    Update a deposit/draft resource with a [JSON Patch](http://jsonpatch.com/).
 
 
     ### What is JSON Patch?
@@ -87,7 +87,7 @@ patch:
 
 
     JSON Patch is specified in [RFC 6902](http://tools.ietf.org/html/rfc6902)
-    from the IETF.
+    by the IETF.
 
 
     ### Simple example
@@ -135,9 +135,9 @@ patch:
           value: Gen Test
     description: >
       A [JSON Patch](http://jsonpatch.com/) object that will update/patch on top
-      of the `metadata` of the resource
+      of the `metadata` of the resource.
 
-      > It should validate against the specified `$schema` of the resource
+      > It should validate against the specified `$schema` of the resource.
     required: true
   responses:
     '200':

spec/paths/deposits@{depid}@[email protected]

@@ -11,8 +11,8 @@ post:
     - Deposits
   summary: Clone/duplicate a draft
   description: |
-    Retrieve a draft records by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a draft record using `deposit_id`.
+    > You need to have at least 'read' access.
   operationId: cloneDeposit
   responses:
     '200':

spec/paths/deposits@{depid}@[email protected]

@@ -9,12 +9,12 @@ parameters:
 post:
   tags:
     - Deposits
-  summary: Edit published deposit
+  summary: Edit a published deposit
   description: >
     To be able to **edit** an already `published` deposit, you should first
     change it's status to `draft`. Only then you can
     [update](#operation/depositUpdate) or [patch](#operation/depositPatch)
-    depending on your needs 
+    depending on your needs.
   operationId: editDeposit
   responses:
     '200':

spec/paths/deposits@{depid}@[email protected]

@@ -11,8 +11,8 @@ post:
     - Deposits
   summary: Add/remove permissions
   description: |
-    Add or remove `user` and `e-group` access to the resource
-    > You need to have 'admin' rights for the deposit to change permissions
+    Add or remove `user` and `e-group` access for a resource.
+    > You need to have 'admin' rights for the deposit to be able to change permissions.
   operationId: permissionsDeposit
   responses:
     '200':

spec/paths/deposits@{depid}@[email protected]

@@ -12,7 +12,7 @@ post:
   summary: Publish to collaboration
   description: >
     Create a new version of the document and make it public to your
-    collaboration
+    collaboration.
   operationId: publishDeposit
   responses:
     '200':

spec/paths/deposits@{depid}@[email protected]

@@ -26,13 +26,13 @@ post:
   summary: Upload files/data
   description: |
     Upload files/data to your analysis, in a specified deposit record.
-    The following type of uploads are possible:
+    The following types of uploads are possible:
       * Local files
       * Git repos
       * URL linked files
 
     The API differentiates between whole repos (saved as .tar) and single files
-    from repos, so the parameter "type" is necessary.
+    from repos, so the parameter `type` is necessary.
   operationId: uploadDeposit
   responses:
     '200':

spec/paths/deposits@{depid}@files.yaml

@@ -11,7 +11,7 @@ get:
     - Deposits
   summary: Get deposit files
   description: |
-    Retrieve all files that are associated with the draft record
+    Retrieve all files that are associated with a draft record.
   responses:
     '200':
       description: List of files
@@ -28,10 +28,10 @@ get:
 post:
   tags:
     - Deposits
-  summary: Upload local files
+  summary: Upload local files.
   description: |
-    Retrieve a draft records by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a draft record using `deposit_id`
+    > You need to have at least 'read' access.
   operationId: filesDeposit
   responses:
     '200':

spec/paths/jsonschemas.yaml

@@ -3,8 +3,8 @@ get:
     - JSON Schemas
   summary: Get a list of available JSON Schemas
   description: >-
-    List of the available JSON schemas. They can be used to create an analysis
-    record
+    List of the available JSON Schemas. They can be used to create an analysis
+    record.
   operationId: getJSONSchemas
   responses:
     '200':
@@ -26,11 +26,11 @@ get:
 post:
   tags:
     - JSON Schemas
-  summary: Create a new JSON Schemas
+  summary: Create a new JSON schema
   description: >
-    Create a new JSON schemas. Add your customized schemas for records and
+    Create a new JSON Schema. Add your customized schemas for records and
     deposits, your corresponding UI form options and ES search mapping for
-    better indexing
+    better indexing.
   operationId: createJSONSchemas
   requestBody:
     content:
@@ -41,7 +41,7 @@ post:
           simple:
             $ref: '#/components/examples/JSONSchemaResource'
     description: |
-      A JSON object that will populate the `Schema` resource
+      A JSON object that will populate the `Schema` resource.
     required: true
   responses:
     '200':

spec/paths/jsonschemas@{name}.yaml

@@ -9,7 +9,7 @@ get:
   tags:
     - JSON Schemas
   summary: Get latest version by name
-  description: Retrieve the latest JSON Schemas for the specified `name`
+  description: Retrieve the latest JSON Schema for a specified `name`.
   operationId: getLatestByName
   responses:
     '200':

spec/paths/jsonschemas@{name}@{version}.yaml

@@ -15,7 +15,7 @@ get:
   tags:
     - JSON Schemas
   summary: Get schema by name and version
-  description: Retrieve the latest JSON Schemas for the specified `name`
+  description: Retrieve the latest JSON Schemas for a specified `name` and `version`.
   operationId: getSchemaByNameAndVersion
   responses:
     '200':
@@ -35,11 +35,11 @@ get:
 put:
   tags:
     - JSON Schemas
-  summary: Update schemas for a specific name and version
+  summary: Update schemas for a specific name and version,
   description: >
-    Create a new JSON schemas. Add your customized schemas for records and
+    Create a new JSON Schema. Add your customized schemas for records and
     deposits, your corresponding UI form options and ES search mapping for
-    better indexing
+    better indexing.
   operationId: updateSchemaByNameAndVersion
   requestBody:
     content:
@@ -50,8 +50,8 @@ put:
           title: My new title
           abstract: Already commited/saved abstract desciption
     description: |
-      A JSON object that will replace the `metadata` field of the resource
-      > It should validate against the specified `$schema` of the resource
+      A JSON object that will replace the `metadata` field of the resource.
+      > It should validate against the specified `$schema` of the resource.
     required: true
   responses:
     '200':
@@ -72,7 +72,7 @@ delete:
   tags:
     - JSON Schemas
   summary: Remove schemas for a specific name and version
-  description: Remove schemas for a specific name and version
+  description: Remove schemas for a specific name and version.
   operationId: deleteSchemaByNameAndVersion
   responses:
     '200':

spec/paths/records.yaml

@@ -8,8 +8,8 @@ get:
     - Search
   summary: Retrieve a list of records
   description: >-
-    Query published records (You need to have at least 'read' access to query
-    them)
+    Query published records.
+    > You need to have at least 'read' access to query them.
   operationId: get_records
   parameters:
     - $ref: '#/components/parameters/query'
@@ -57,7 +57,7 @@ post:
   tags:
     - Records
   summary: Create a record
-  description: Create a record
+  description: Create a record.
   operationId: create_record
   responses:
     '200':

spec/paths/users@{username}.yaml

@@ -41,7 +41,7 @@ get:
 put:
   tags:
     - User
-  summary: Updated user
+  summary: Update user
   description: This can only be done by the logged in user.
   operationId: updateUser
   parameters:

spec/paths/workflows@reana@all@record@{pid}.yaml

@@ -4,7 +4,7 @@ get:
   tags:
     - Workflows
   summary: Get all the workflows
-  description: Get all the workflows (created and deleted) from the user
+  description: Get all the workflows (created and deleted) from the user.
   operationId: reana_workflow_all
   responses:
     '200':