opensource/supermq
1
0
Fork 0
mirror of https://github.com/absmach/supermq.git synced 2026-06-23 06:40:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

NOISSUE - Update API documentation (#2550)

Browse Source 
Signed-off-by: Felix Gateru <felix.gateru@gmail.com>
This commit is contained in:
Felix Gateru
2024-11-26 11:36:27 +03:00
committed by GitHub
parent b20b45023d
commit 8d4e752274
3 changed files with 31 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
api/openapi/auth.yml
+18 -94
View File
@@ -20,17 +20,25 @@ servers:
- url: https://localhost:8189
tags:
- name: Auth
description: Everything about your Authentication and Authorization.
externalDocs:
description: Find out more about auth
url: https://docs.magistrala.abstractmachines.fr/
- name: Keys
description: Everything about your Keys.
externalDocs:
description: Find out more about keys
url: https://docs.magistrala.abstractmachines.fr/
- name: Domains
description: Everything about your Domains.
externalDocs:
description: Find out more about domains
url: https://docs.magistrala.abstractmachines.fr/
- name: Health
description: Service health check endpoint.
externalDocs:
description: Find out more about health check
url: https://docs.magistrala.abstractmachines.fr/
paths:
/domains:
post:
@@ -372,73 +380,18 @@ paths:
"500":
$ref: "#/components/responses/ServiceError"
/policies:
post:
operationId: addPolicies
summary: Creates new policies.
description: |
Creates new policies. Only admin can use this endpoint. Therefore, you need an authentication token for the admin.
Also, only policies defined on the system are allowed to add. For more details, please see the docs for Authorization.
tags:
- Auth
requestBody:
$ref: "#/components/requestBodies/PoliciesReq"
responses:
"201":
description: Policies created.
"400":
description: Failed due to malformed JSON.
"401":
description: Missing or invalid access token provided.
"403":
description: Unauthorized access token provided.
"404":
description: A non-existent entity request.
"409":
description: Failed due to using an existing email address.
"415":
description: Missing or invalid content type.
"500":
$ref: "#/components/responses/ServiceError"
/policies/delete:
post:
operationId: deletePolicies
summary: Deletes policies.
description: |
Deletes policies. Only admin can use this endpoint. Therefore, you need an authentication token for the admin.
Also, only policies defined on the system are allowed to delete. For more details, please see the docs for Authorization.
tags:
- Auth
requestBody:
$ref: "#/components/requestBodies/PoliciesReq"
responses:
"204":
description: Policies deleted.
"400":
description: Failed due to malformed JSON.
"401":
description: Missing or invalid access token provided.
"404":
description: A non-existent entity request.
"409":
description: Failed due to using an existing email address.
"415":
description: Missing or invalid content type.
"500":
$ref: "#/components/responses/ServiceError"
/users/{memberID}/domains:
/users/{userID}/domains:
get:
tags:
- Domains
summary: List users in a group
summary: Lists domains associated with a user.
description: |
Retrieves a list of users in a domain. Due to performance concerns, data
Retrieves a list of domains associated with a user. Due to performance concerns, data
is retrieved in subsets. The API must ensure that the entire
dataset is consumed either by making subsequent requests, or by
increasing the subset size of the initial request.
parameters:
- $ref: "users.yml#/components/parameters/MemberID"
- $ref: "users.yml#/components/parameters/UserID"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Metadata"
@@ -465,7 +418,7 @@ paths:
get:
summary: Retrieves service health check info.
tags:
- health
- Health
security: []
responses:
"200":
@@ -677,27 +630,6 @@ components:
description: Time when the Key expires. If this field is missing,
that means that Key is valid indefinitely.
PoliciesReqSchema:
type: object
properties:
object:
type: string
description: |
Specifies an object field for the field.
Object indicates application objects such as ThingID.
subjects:
type: array
minItems: 1
uniqueItems: true
items:
type: string
policies:
type: array
minItems: 1
uniqueItems: true
items:
type: string
parameters:
DomainID:
name: domainID
@@ -834,14 +766,6 @@ components:
example: 23456
description: Number of seconds issued token is valid for.
PoliciesReq:
description: JSON-formatted document describing adding policies request.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PoliciesReqSchema"
responses:
ServiceError:
description: Unexpected server-side error occurred.
api/openapi/things.yml
+8 -11
View File
@@ -263,7 +263,7 @@ paths:
/{domainID}/things/{thingID}/secret:
patch:
operationId: updateThingSecret
summary: Updates Secret of the identified thing.
summary: Updates secret of the identified thing.
description: |
Updates secret of the identified in thing. Secret is updated using
authorization token and the new received info. Update is performed by replacing current key with a new one.
@@ -363,7 +363,7 @@ paths:
operationId: shareThing
summary: Shares a thing
description: |
Shares a specific thing that is identifier by the thing ID.
Shares a specific thing that is identified by the thing ID.
tags:
- Things
parameters:
@@ -394,7 +394,7 @@ paths:
operationId: unshareThing
summary: Unshares a thing
description: |
Unshares a specific thing that is identifier by the thing ID.
Unshares a specific thing that is identified by the thing ID.
tags:
- Things
parameters:
@@ -1100,12 +1100,9 @@ components:
"bb7edb32-2eac-4aad-aebe-ed96fe073879",
]
relation:
type: array
minItems: 0
items:
type: string
example: ["m_write", "g_add"]
description: Policy relations.
type: string
example: "editor"
description: Policy relation.
required:
- user_ids
- relation
@@ -1126,7 +1123,7 @@ components:
]
relation:
type: string
example: "m_write"
example: "editor"
description: Policy relations.
member_kind:
type: string
@@ -1153,7 +1150,7 @@ components:
]
relation:
type: string
example: "m_write"
example: "editor"
description: Policy relations.
required:
- users_ids
api/openapi/users.yml
+5 -3
View File
@@ -550,7 +550,7 @@ paths:
"500":
$ref: "#/components/responses/ServiceError"
/groups/{groupID}/users:
/{domainID}/groups/{groupID}/users:
get:
operationId: listUsersInGroup
tags:
@@ -562,6 +562,7 @@ paths:
dataset is consumed either by making subsequent requests, or by
increasing the subset size of the initial request.
parameters:
- $ref: "auth.yml#/components/parameters/DomainID"
- $ref: "#/components/parameters/GroupID"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
@@ -588,7 +589,7 @@ paths:
"500":
$ref: "#/components/responses/ServiceError"
/channels/{channelID}/users:
/{domainID}/channels/{channelID}/users:
get:
operationId: listUsersInChannel
tags:
@@ -600,6 +601,7 @@ paths:
dataset is consumed either by making subsequent requests, or by
increasing the subset size of the initial request.
parameters:
- $ref: "auth.yml#/components/parameters/DomainID"
- $ref: "#/components/parameters/ChannelID"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
@@ -1825,7 +1827,7 @@ components:
ChannelID:
name: channelID
description: Unique group identifier.
description: Unique channel identifier.
in: path
schema:
type: string