[#6092] docs(core): add credential openapi document #6088
Conversation
…che#6039) ### What changes were proposed in this pull request? Remove the unnecessary `CONTRIBUTING` file under `.github` folder. ### Why are the changes needed? It's not necessary to add this file in `.github` folder. Fix: apache#6008 ### Does this PR introduce _any_ user-facing change? No. ### How was this patch tested? N/A
FANNG1
changed the title
|
@jerryshao @mchades @yuqi1129 PTAL |
docs/open-api/credentials.yaml
Outdated
| get: | ||
| tags: | ||
| - credentials | ||
| summary: List credentials for metadata object |
There was a problem hiding this comment.
Summary will be used as the title in the sidebar (https://gravitino.apache.org/docs/0.7.0-incubating/api/rest/list-catalogs), it should not be too long.
docs/open-api/credentials.yaml
Outdated
| properties: | ||
| credentialType: | ||
| type: string | ||
| description: The type of the credential |
There was a problem hiding this comment.
I believe we have a enum for this field.
There was a problem hiding this comment.
we didn't define an enum because we should support custom credentials. add the build-in credentials
docs/open-api/credentials.yaml
Outdated
| description: The type of the credential | ||
| expireTimeInMs: | ||
| type: long | ||
| description: The expire time of the credential |
There was a problem hiding this comment.
Please amend the description so that users know what this long number is.
| @@ -68,7 +59,7 @@ components: | |||
| type: string | |||
| description: The type of the credential, for example, s3-token, s3-secret-key, oss-token, oss-secret-key, gcs-token, adls-token, azure-account-key, etc. | |||
| expireTimeInMs: | |||
| type: long | |||
| type: integer | |||
| description: The expiration time of the credential in milliseconds since the epoch, 0 means not expire. | |||
There was a problem hiding this comment.
Gocha. :)
This is not supposed to be a time elapsed since epoch.
It is supposed to be time duration in milliseconds when the credential (e.g. a certificate) will expire.
There was a problem hiding this comment.
It's not an time duration, because the credential may need some time to transfer from server side to client side, which makes duration not correct.
| properties: | ||
| credentialType: | ||
| type: string | ||
| description: The type of the credential, for example, s3-token, s3-secret-key, oss-token, oss-secret-key, gcs-token, adls-token, azure-account-key, etc. |
There was a problem hiding this comment.
Thanks for mentioning the credential type examples.
Although not in the scope of this PR, I'm still wondering if we need to add an API for users to retrieve a list of supported credential types.
There was a problem hiding this comment.
I couldn't figure out usage scenarios about this API, we could add it if requried.
| - expireTimeInMs | ||
| - credentialInfo | ||
| properties: | ||
| credentialType: |
There was a problem hiding this comment.
I wouldn't call this credentialType because the property has a well-defined scope.
E.g. when I'm modeling a Person, I'll simply add a gender property rather than
naming it as personGender.
This can be pretty simple, e.g.
{"type": "gcs-token", "expireTimeInMs": 12345, "data": {"token": "secret"}}
There was a problem hiding this comment.
Yes, thanks for pointing this out, I agree with you, how about keeping this as it has been published as API? I will try to use the short style for new features.
### What changes were proposed in this pull request? add credential openapi document ### Why are the changes needed? Fix: apache#6092 ### Does this PR introduce _any_ user-facing change? no ### How was this patch tested? just document
What changes were proposed in this pull request?
add credential openapi document
Why are the changes needed?
Fix: #6092
Does this PR introduce any user-facing change?
no
How was this patch tested?
just document