mirror of
https://github.com/nextcloud/server.git
synced 2026-04-22 14:50:17 -04:00
Merge pull request #39634 from nextcloud/feature/openapi/core/text-processing-api
core: Document text processing API
This commit is contained in:
Kate
GitHub
commit
05f02fd5c5
3 changed files with 519 additions and 0 deletions
|
|
@ -27,6 +27,7 @@ declare(strict_types=1);
|
|||
namespace OC\Core\Controller;
|
||||
|
||||
use InvalidArgumentException;
|
||||
use OCA\Core\ResponseDefinitions;
|
||||
use OCP\AppFramework\Http;
|
||||
use OCP\AppFramework\Http\DataResponse;
|
||||
use OCP\Common\Exception\NotFoundException;
|
||||
|
|
@ -41,6 +42,9 @@ use Psr\Container\ContainerInterface;
|
|||
use Psr\Container\NotFoundExceptionInterface;
|
||||
use Psr\Log\LoggerInterface;
|
||||
|
||||
/**
|
||||
* @psalm-import-type CoreTextProcessingTask from ResponseDefinitions
|
||||
*/
|
||||
class TextProcessingApiController extends \OCP\AppFramework\OCSController {
|
||||
public function __construct(
|
||||
string $appName,
|
||||
|
|
@ -58,10 +62,13 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
|
|||
* This endpoint returns all available LanguageModel task types
|
||||
*
|
||||
* @PublicPage
|
||||
*
|
||||
* @return DataResponse<Http::STATUS_OK, array{types: array{id: string, name: string, description: string}[]}, array{}>
|
||||
*/
|
||||
public function taskTypes(): DataResponse {
|
||||
$typeClasses = $this->languageModelManager->getAvailableTaskTypes();
|
||||
$types = [];
|
||||
/** @var string $typeClass */
|
||||
foreach ($typeClasses as $typeClass) {
|
||||
try {
|
||||
/** @var ITaskType $object */
|
||||
|
|
@ -88,6 +95,17 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
|
|||
* @PublicPage
|
||||
* @UserRateThrottle(limit=20, period=120)
|
||||
* @AnonRateThrottle(limit=5, period=120)
|
||||
*
|
||||
* @param string $input Input text
|
||||
* @param string $type Type of the task
|
||||
* @param string $appId ID of the app that will execute the task
|
||||
* @param string $identifier An arbitrary identifier for the task
|
||||
*
|
||||
* @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED, array{message: string}, array{}>
|
||||
*
|
||||
* 200: Task scheduled successfully
|
||||
* 400: Scheduling task is not possible
|
||||
* 412: Scheduling task is not possible
|
||||
*/
|
||||
public function schedule(string $input, string $type, string $appId, string $identifier = ''): DataResponse {
|
||||
try {
|
||||
|
|
@ -114,6 +132,11 @@ class TextProcessingApiController extends \OCP\AppFramework\OCSController {
|
|||
*
|
||||
* @PublicPage
|
||||
* @param int $id The id of the task
|
||||
*
|
||||
* @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
|
||||
*
|
||||
* 200: Task returned
|
||||
* 404: Task not found
|
||||
*/
|
||||
public function getTask(int $id): DataResponse {
|
||||
try {
|
||||
|
|
|
|||
|
|
@ -126,6 +126,17 @@ namespace OCA\Core;
|
|||
* subline: string,
|
||||
* shareWithDisplayNameUnique: string,
|
||||
* }
|
||||
*
|
||||
* @psalm-type CoreTextProcessingTask = array{
|
||||
* id: ?int,
|
||||
* type: string,
|
||||
* status: 0|1|2|3|4,
|
||||
* userId: ?string,
|
||||
* appId: string,
|
||||
* input: string,
|
||||
* output: ?string,
|
||||
* identifier: string,
|
||||
* }
|
||||
*/
|
||||
class ResponseDefinitions {
|
||||
}
|
||||
|
|
|
|||
|
|
@ -372,6 +372,70 @@
|
|||
}
|
||||
}
|
||||
},
|
||||
"TextProcessingTask": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"type",
|
||||
"status",
|
||||
"userId",
|
||||
"appId",
|
||||
"input",
|
||||
"output",
|
||||
"identifier"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"nullable": true
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
}
|
||||
]
|
||||
},
|
||||
"userId": {
|
||||
"type": "string",
|
||||
"nullable": true
|
||||
},
|
||||
"appId": {
|
||||
"type": "string"
|
||||
},
|
||||
"input": {
|
||||
"type": "string"
|
||||
},
|
||||
"output": {
|
||||
"type": "string",
|
||||
"nullable": true
|
||||
},
|
||||
"identifier": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"UnifiedSearchProvider": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
|
|
@ -4181,6 +4245,427 @@
|
|||
}
|
||||
}
|
||||
},
|
||||
"/ocs/v2.php/textprocessing/tasktypes": {
|
||||
"get": {
|
||||
"operationId": "text_processing_api-task-types",
|
||||
"summary": "This endpoint returns all available LanguageModel task types",
|
||||
"tags": [
|
||||
"text_processing_api"
|
||||
],
|
||||
"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": [
|
||||
"types"
|
||||
],
|
||||
"properties": {
|
||||
"types": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"name",
|
||||
"description"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/ocs/v2.php/textprocessing/schedule": {
|
||||
"post": {
|
||||
"operationId": "text_processing_api-schedule",
|
||||
"summary": "This endpoint allows scheduling a language model task",
|
||||
"tags": [
|
||||
"text_processing_api"
|
||||
],
|
||||
"security": [
|
||||
{},
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "input",
|
||||
"in": "query",
|
||||
"description": "Input text",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "type",
|
||||
"in": "query",
|
||||
"description": "Type of the task",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "appId",
|
||||
"in": "query",
|
||||
"description": "ID of the app that will execute the task",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "identifier",
|
||||
"in": "query",
|
||||
"description": "An arbitrary identifier for the task",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": ""
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Task scheduled successfully",
|
||||
"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": [
|
||||
"task"
|
||||
],
|
||||
"properties": {
|
||||
"task": {
|
||||
"$ref": "#/components/schemas/TextProcessingTask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Scheduling task is not possible",
|
||||
"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": [
|
||||
"message"
|
||||
],
|
||||
"properties": {
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"412": {
|
||||
"description": "Scheduling task is not possible",
|
||||
"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": [
|
||||
"message"
|
||||
],
|
||||
"properties": {
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/ocs/v2.php/textprocessing/task/{id}": {
|
||||
"get": {
|
||||
"operationId": "text_processing_api-get-task",
|
||||
"summary": "This endpoint allows checking the status and results of a task. Tasks are removed 1 week after receiving their last update.",
|
||||
"tags": [
|
||||
"text_processing_api"
|
||||
],
|
||||
"security": [
|
||||
{},
|
||||
{
|
||||
"bearer_auth": []
|
||||
},
|
||||
{
|
||||
"basic_auth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"description": "The id of the task",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"format": "int64"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "OCS-APIRequest",
|
||||
"in": "header",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "true"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Task 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",
|
||||
"required": [
|
||||
"task"
|
||||
],
|
||||
"properties": {
|
||||
"task": {
|
||||
"$ref": "#/components/schemas/TextProcessingTask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Task not found",
|
||||
"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": [
|
||||
"message"
|
||||
],
|
||||
"properties": {
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"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": [
|
||||
"message"
|
||||
],
|
||||
"properties": {
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/status.php": {
|
||||
"get": {
|
||||
"operationId": "get-status",
|
||||
|
|
|
|||
Loading…
Reference in a new issue