mirror of
https://github.com/nextcloud/server.git
synced 2026-04-15 22:11:17 -04:00
user_ldap: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
This commit is contained in:
jld3103
parent
79316e1169
commit
61a13bed4d
2 changed files with 410 additions and 76 deletions
|
|
@ -29,6 +29,7 @@ use OC\Security\IdentityProof\Manager;
|
|||
use OCA\User_LDAP\Configuration;
|
||||
use OCA\User_LDAP\ConnectionFactory;
|
||||
use OCA\User_LDAP\Helper;
|
||||
use OCP\AppFramework\Http;
|
||||
use OCP\AppFramework\Http\DataResponse;
|
||||
use OCP\AppFramework\OCS\OCSBadRequestException;
|
||||
use OCP\AppFramework\OCS\OCSException;
|
||||
|
|
@ -76,42 +77,10 @@ class ConfigAPIController extends OCSController {
|
|||
}
|
||||
|
||||
/**
|
||||
* Creates a new (empty) configuration and returns the resulting prefix
|
||||
*
|
||||
* Example: curl -X POST -H "OCS-APIREQUEST: true" -u $admin:$password \
|
||||
* https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config
|
||||
*
|
||||
* results in:
|
||||
*
|
||||
* <?xml version="1.0"?>
|
||||
* <ocs>
|
||||
* <meta>
|
||||
* <status>ok</status>
|
||||
* <statuscode>200</statuscode>
|
||||
* <message>OK</message>
|
||||
* </meta>
|
||||
* <data>
|
||||
* <configID>s40</configID>
|
||||
* </data>
|
||||
* </ocs>
|
||||
*
|
||||
* Failing example: if an exception is thrown (e.g. Database connection lost)
|
||||
* the detailed error will be logged. The output will then look like:
|
||||
*
|
||||
* <?xml version="1.0"?>
|
||||
* <ocs>
|
||||
* <meta>
|
||||
* <status>failure</status>
|
||||
* <statuscode>999</statuscode>
|
||||
* <message>An issue occurred when creating the new config.</message>
|
||||
* </meta>
|
||||
* <data/>
|
||||
* </ocs>
|
||||
*
|
||||
* For JSON output provide the format=json parameter
|
||||
* Create a new (empty) configuration and return the resulting prefix
|
||||
*
|
||||
* @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin)
|
||||
* @return DataResponse
|
||||
* @return DataResponse<Http::STATUS_OK, array{configID: string}, array{}>
|
||||
* @throws OCSException
|
||||
*/
|
||||
public function create() {
|
||||
|
|
@ -128,27 +97,15 @@ class ConfigAPIController extends OCSController {
|
|||
}
|
||||
|
||||
/**
|
||||
* Deletes a LDAP configuration, if present.
|
||||
*
|
||||
* Example:
|
||||
* curl -X DELETE -H "OCS-APIREQUEST: true" -u $admin:$password \
|
||||
* https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config/s60
|
||||
*
|
||||
* <?xml version="1.0"?>
|
||||
* <ocs>
|
||||
* <meta>
|
||||
* <status>ok</status>
|
||||
* <statuscode>200</statuscode>
|
||||
* <message>OK</message>
|
||||
* </meta>
|
||||
* <data/>
|
||||
* </ocs>
|
||||
* Delete a LDAP configuration
|
||||
*
|
||||
* @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin)
|
||||
* @param string $configID
|
||||
* @return DataResponse
|
||||
* @throws OCSBadRequestException
|
||||
* @param string $configID ID of the config
|
||||
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
|
||||
* @throws OCSException
|
||||
* @throws OCSNotFoundException Config not found
|
||||
*
|
||||
* 200: Config deleted successfully
|
||||
*/
|
||||
public function delete($configID) {
|
||||
try {
|
||||
|
|
@ -167,28 +124,17 @@ class ConfigAPIController extends OCSController {
|
|||
}
|
||||
|
||||
/**
|
||||
* Modifies a configuration
|
||||
*
|
||||
* Example:
|
||||
* curl -X PUT -d "configData[ldapHost]=ldaps://my.ldap.server&configData[ldapPort]=636" \
|
||||
* -H "OCS-APIREQUEST: true" -u $admin:$password \
|
||||
* https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config/s60
|
||||
*
|
||||
* <?xml version="1.0"?>
|
||||
* <ocs>
|
||||
* <meta>
|
||||
* <status>ok</status>
|
||||
* <statuscode>200</statuscode>
|
||||
* <message>OK</message>
|
||||
* </meta>
|
||||
* <data/>
|
||||
* </ocs>
|
||||
* Modify a configuration
|
||||
*
|
||||
* @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin)
|
||||
* @param string $configID
|
||||
* @param array $configData
|
||||
* @return DataResponse
|
||||
* @param string $configID ID of the config
|
||||
* @param array<string, mixed> $configData New config
|
||||
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
|
||||
* @throws OCSException
|
||||
* @throws OCSBadRequestException Modifying config is not possible
|
||||
* @throws OCSNotFoundException Config not found
|
||||
*
|
||||
* 200: Config returned
|
||||
*/
|
||||
public function modify($configID, $configData) {
|
||||
try {
|
||||
|
|
@ -220,8 +166,9 @@ class ConfigAPIController extends OCSController {
|
|||
}
|
||||
|
||||
/**
|
||||
* Retrieves a configuration
|
||||
* Get a configuration
|
||||
*
|
||||
* Output can look like this:
|
||||
* <?xml version="1.0"?>
|
||||
* <ocs>
|
||||
* <meta>
|
||||
|
|
@ -285,10 +232,13 @@ class ConfigAPIController extends OCSController {
|
|||
* </ocs>
|
||||
*
|
||||
* @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin)
|
||||
* @param string $configID
|
||||
* @param bool|string $showPassword
|
||||
* @return DataResponse
|
||||
* @param string $configID ID of the config
|
||||
* @param bool $showPassword Whether to show the password
|
||||
* @return DataResponse<Http::STATUS_OK, array<string, mixed>, array{}>
|
||||
* @throws OCSException
|
||||
* @throws OCSNotFoundException Config not found
|
||||
*
|
||||
* 200: Config returned
|
||||
*/
|
||||
public function show($configID, $showPassword = false) {
|
||||
try {
|
||||
|
|
@ -296,7 +246,7 @@ class ConfigAPIController extends OCSController {
|
|||
|
||||
$config = new Configuration($configID);
|
||||
$data = $config->getConfiguration();
|
||||
if (!(int)$showPassword) {
|
||||
if (!$showPassword) {
|
||||
$data['ldapAgentPassword'] = '***';
|
||||
}
|
||||
foreach ($data as $key => $value) {
|
||||
|
|
|
|||
384
apps/user_ldap/openapi.json
Normal file
384
apps/user_ldap/openapi.json
Normal file
|
|
@ -0,0 +1,384 @@
|
|||
{
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"title": "user_ldap",
|
||||
"version": "0.0.1",
|
||||
"description": "This application enables administrators to connect Nextcloud to an LDAP-based user directory.",
|
||||
"license": {
|
||||
"name": "agpl"
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"basic_auth": {
|
||||
"type": "http",
|
||||
"scheme": "basic"
|
||||
},
|
||||
"bearer_auth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer"
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"OCSMeta": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"status",
|
||||
"statuscode"
|
||||
],
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"statuscode": {
|
||||
"type": "integer"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"totalitems": {
|
||||
"type": "string"
|
||||
},
|
||||
"itemsperpage": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"paths": {
|
||||
"/ocs/v2.php/apps/user_ldap/api/v1/config": {
|
||||
"post": {
|
||||
"operationId": "configapi-create",
|
||||
"summary": "Create a new (empty) configuration and return the resulting prefix",
|
||||
"description": "This endpoint requires admin access",
|
||||
"tags": [
|
||||
"configapi"
|
||||
],
|
||||
"security": [
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"ocs"
|
||||
],
|
||||
"properties": {
|
||||
"ocs": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"meta",
|
||||
"data"
|
||||
],
|
||||
"properties": {
|
||||
"meta": {
|
||||
"$ref": "#/components/schemas/OCSMeta"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"configID"
|
||||
],
|
||||
"properties": {
|
||||
"configID": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}": {
|
||||
"get": {
|
||||
"operationId": "configapi-show",
|
||||
"summary": "Get a configuration",
|
||||
"description": "This endpoint requires admin access",
|
||||
"tags": [
|
||||
"configapi"
|
||||
],
|
||||
"security": [
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "showPassword",
|
||||
"in": "query",
|
||||
"description": "Whether to show the password",
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"default": 0
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "configID",
|
||||
"in": "path",
|
||||
"description": "ID of the config",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Config returned",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"ocs"
|
||||
],
|
||||
"properties": {
|
||||
"ocs": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"meta",
|
||||
"data"
|
||||
],
|
||||
"properties": {
|
||||
"meta": {
|
||||
"$ref": "#/components/schemas/OCSMeta"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Config not found",
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"operationId": "configapi-modify",
|
||||
"summary": "Modify a configuration",
|
||||
"description": "This endpoint requires admin access",
|
||||
"tags": [
|
||||
"configapi"
|
||||
],
|
||||
"security": [
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "configData",
|
||||
"in": "query",
|
||||
"description": "New config",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "configID",
|
||||
"in": "path",
|
||||
"description": "ID of the config",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Config returned",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"ocs"
|
||||
],
|
||||
"properties": {
|
||||
"ocs": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"meta",
|
||||
"data"
|
||||
],
|
||||
"properties": {
|
||||
"meta": {
|
||||
"$ref": "#/components/schemas/OCSMeta"
|
||||
},
|
||||
"data": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Modifying config is not possible",
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Config not found",
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"operationId": "configapi-delete",
|
||||
"summary": "Delete a LDAP configuration",
|
||||
"description": "This endpoint requires admin access",
|
||||
"tags": [
|
||||
"configapi"
|
||||
],
|
||||
"security": [
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "configID",
|
||||
"in": "path",
|
||||
"description": "ID of the config",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Config deleted successfully",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"ocs"
|
||||
],
|
||||
"properties": {
|
||||
"ocs": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"meta",
|
||||
"data"
|
||||
],
|
||||
"properties": {
|
||||
"meta": {
|
||||
"$ref": "#/components/schemas/OCSMeta"
|
||||
},
|
||||
"data": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Config not found",
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"tags": []
|
||||
}
|
||||
Loading…
Reference in a new issue