From c7e4f7bc3a8bbb898cf1636f7f4698a85ddb4d52 Mon Sep 17 00:00:00 2001 From: fflorent Date: Tue, 17 Dec 2024 18:14:22 +0100 Subject: [PATCH] Fix the SCIM API documentation --- api/scim/users.yml | 8 ++++---- help/en/docs/api.md | 20 +++++++++++++------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/api/scim/users.yml b/api/scim/users.yml index 6da1c71e4..764aaa808 100644 --- a/api/scim/users.yml +++ b/api/scim/users.yml @@ -81,7 +81,7 @@ paths: - users - scim parameters: - - $ref: '#/components/parameters/userIdPathParam' + - $ref: '#/components/params/userIdPathParam' responses: '200': description: Successfully retrieved user details. @@ -106,7 +106,7 @@ paths: - users - scim parameters: - - $ref: '#/params/userIdPathParam' + - $ref: '#/components/params/userIdPathParam' requestBody: description: Updated data for the user. required: true @@ -139,7 +139,7 @@ paths: - users - scim parameters: - - $ref: '#/params/userIdPathParam' + - $ref: '#/components/params/userIdPathParam' requestBody: description: Data for the partial update of the user. required: true @@ -199,7 +199,7 @@ paths: - users - scim parameters: - - $ref: '#/params/userIdPathParam' + - $ref: '#/components/params/userIdPathParam' responses: '204': description: User deleted successfully. diff --git a/help/en/docs/api.md b/help/en/docs/api.md index d07fccbdb..fad9c9c7e 100644 --- a/help/en/docs/api.md +++ b/help/en/docs/api.md @@ -323,7 +323,8 @@ Currently, only the users themselves are allowed to delete their own accounts.

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Update a user by ID

⚠️ This operation override all the user's information. In order to pass only some properties to update, please use PATCH instead.

-
Authorizations:
ApiKey
Request Body schema: application/scim+json

Updated data for the user.

+
Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+
Request Body schema: application/scim+json

Updated data for the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string

The unique username.

object
Array of objects
displayName
string

the display name of the user

preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

@@ -335,7 +336,8 @@ Currently, only the users themselves are allowed to delete their own accounts.

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the partial update of the user.

+

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+
Request Body schema: application/scim+json

Data for the partial update of the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:PatchOp"
Array of objects

Responses

Request samples

Content type
application/scim+json
{}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Delete a user by ID.

⚠️ This action cannot be undone, please be cautious when using this endpoint ⚠️

-
Authorizations:
ApiKey

Responses

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+

Responses

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Update a user by ID

⚠️ This operation override all the user's information. In order to pass only some properties to update, please use PATCH instead.

-
Authorizations:
ApiKey
Request Body schema: application/scim+json

Updated data for the user.

+
Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+
Request Body schema: application/scim+json

Updated data for the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:schemas:core:2.0:User"
userName
string

The unique username.

object
Array of objects
displayName
string

the display name of the user

preferredLanguage
string

Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.

@@ -437,7 +441,8 @@ Currently, only the users themselves are allowed to delete their own accounts.

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
Request Body schema: application/scim+json

Data for the partial update of the user.

+

Request samples

Content type
application/scim+json
{
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Partially update a user by ID

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+
Request Body schema: application/scim+json

Data for the partial update of the user.

schemas
Array of strings
Items Value: "urn:ietf:params:scim:api:messages:2.0:PatchOp"
Array of objects

Responses

Request samples

Content type
application/scim+json
{}

Response samples

Content type
application/scim+json
{
  • "meta": {
    • "resourceType": "User",
    • "location": "/api/scim/v2/Users/1"
    },
  • "id": "1",
  • "schemas": [
    • "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
  • "userName": "john.doe@example.com",
  • "name": {
    • "formatted": "John Doe"
    },
  • "emails": [
    • {
      • "value": "john.doe@example.com",
      • "primary": true
      }
    ],
  • "displayName": "John Doe",
  • "preferredLanguage": "en",
  • "locale": "en",
  • "photos": []
}

Delete a user by ID.

⚠️ This action cannot be undone, please be cautious when using this endpoint ⚠️

-
Authorizations:
ApiKey

Responses

Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+

Responses