Authorization headers are not consistently documented in the swagger API

[brianraymor]

Is there a formal way to document security schemes in swagger?

For example>

POST ../token - Returns a bearer access token that must be passed as a parameter to requests that require authorization such as creating a new Collection.

but when I review one example:

POST ../collections - Create a new Collection

There is no reference for how the access token is passed in the request?

It only seems to be documented in the description for:

GET ../collections -
When the visibility parameter is unspecified or set to PUBLIC, a list of all public collections is returned. The Authorization header is not required. If a collection in the list has been deleted, then it is annotated with tombstone set to True.

When the visibility parameter is set to PRIVATE, a list of all private collections that the user is authorized to access is returned. The Authorization header is required. If a collection in the list is a private revision of a public collection, then it is

[Bento007]

We only documented it when it is an optional parameter that affects the response. We can add more documentation to the /v1/auth/token: POST endpoint with instructions on how it should be used.

The openapi spec does inform the user when authentication is required. What other details would you like?

[brianraymor]

I was curious about whether there is formal markdown that can be added as a security schema to all requests that MAY require an authorization header.

[Bento007]

I'll add some markdown to endpoint that required auth. Openapi doesn't do it for us. It only gives us the little padlock next to the endpoint.

[brianraymor]

For example, I was wondering about - OAI/OpenAPI-Specification#14 (comment)

[Bento007]

We have that defined in the openapi spec.

single-cell-data-portal/backend/config/curation-api.yml

Lines 60 to 62 in 6404a80

	security:
	- curatorAccessLenient: []
	- {}

[brianraymor]

GET /v1/collections/{uuid}

Optional: provide your access token in the request header as Authentication: Bearer <access_token>.

Is it optional or is it required in specific scenarios?

---

PATCH /v1/collections/{uuid}

Optional: provide your access token in the request header as Authentication: Bearer <access_token>.

Isn't it always required?

---

POST /v1/collections/{uuid}/datasets

No reference to authentication token?

---

GET /v1/collections/{uuid]/datasets/{uuid}

No reference to authentication token?

---

GET .../assets

No reference to authentication token?

---

[Bento007]

The endpoints with no authentication token reference do not use the token. I added further details to the other two #3332

[brianraymor]

So - POST /v1/collections/{uuid}/datasets - does not require a authentication token?

Quick test without passing the headers:

<Response [401]>

HTTPError Traceback (most recent call last)
Input In [10], in <cell line: 10>()
8 r = requests.post(url)
9 display(r)
---> 10 r.raise_for_status()
11 dataset_id = r.json()['dataset_id']
12 display(dataset_id)

File ~/.pyenv/versions/3.9.11/envs/env/lib/python3.9/site-packages/requests/models.py:960, in Response.raise_for_status(self)
957 http_error_msg = u'%s Server Error: %s for url: %s' % (self.status_code, reason, self.url)
959 if http_error_msg:
--> 960 raise HTTPError(http_error_msg, response=self)

HTTPError: 401 Client Error: UNAUTHORIZED for url: https://api.cellxgene.dev.single-cell.czi.technology/curation/v1/collections/9361db0a-ce3f-4e89-949c-0dd3e7297f37/datasets/

[Bento007]

You're right we do. My mistake. Thank you @danieljhegeman for adding it in.

[brianraymor]

@Bento007 - LGTM.