Skip to content

Commit

Permalink
feat(ControllerMethod): Add documentation for CORS endpoints
Browse files Browse the repository at this point in the history 
Signed-off-by: provokateurin <[email protected]>
  • Loading branch information
@provokateurin
provokateurin committed Jan 6, 2025
1 parent 3794c04 commit 1312938
Show file tree
Hide file tree
Showing 6 changed files with 317 additions and 2 deletions.
3 changes: 2 additions & 1 deletion generate-spec.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,7 @@
$isIgnored = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'IgnoreOpenAPI');
$isPasswordConfirmation = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'PasswordConfirmationRequired');
$isExApp = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'ExAppRequired');
$isCORS = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'CORS');
$scopes = Helpers::getOpenAPIAttributeScopes($classMethod, $routeName);

if ($isIgnored) {
Expand Down Expand Up @@ -505,7 +506,7 @@
];
}

$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isAdmin, $isDeprecated, $isPasswordConfirmation);
$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isAdmin, $isDeprecated, $isPasswordConfirmation, $isCORS);
if ($classMethodInfo->returns !== []) {
Logger::error($routeName, 'Returns an invalid response');
continue;
Expand Down
13 changes: 12 additions & 1 deletion src/ControllerMethod.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,14 @@ public function __construct(
) {
}

public static function parse(string $context, array $definitions, ClassMethod $method, bool $isAdmin, bool $isDeprecated, bool $isPasswordConfirmation): ControllerMethod {
public static function parse(string $context,
array $definitions,
ClassMethod $method,
bool $isAdmin,
bool $isDeprecated,
bool $isPasswordConfirmation,
bool $isCORS,
): ControllerMethod {
global $phpDocParser, $lexer, $allowMissingDocs;

$parameters = [];
Expand Down Expand Up @@ -210,6 +217,10 @@ public static function parse(string $context, array $definitions, ClassMethod $m
$methodDescription[] = 'This endpoint requires password confirmation';
}

if ($isCORS) {
$methodDescription[] = 'This endpoint allows CORS requests';
}

if (count($methodDescription) == 1) {
$methodSummary = $methodDescription[0];
$methodDescription = [];
Expand Down
2 changes: 2 additions & 0 deletions tests/appinfo/routes.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,5 +74,7 @@
['name' => 'Settings#parameterRequestBody', 'url' => '/api/{apiVersion}/parameterPATCH', 'verb' => 'PATCH', 'postfix' => 'PATCH', 'requirements' => ['apiVersion' => '(v2)']],
['name' => 'Settings#objectDefaults', 'url' => '/api/{apiVersion}/objectDefaults', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
['name' => 'Settings#whitespace', 'url' => '/api/{apiVersion}/whitespace', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
['name' => 'Settings#withCorsAnnotation', 'url' => '/api/{apiVersion}/cors/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
['name' => 'Settings#withCorsAttribute', 'url' => '/api/{apiVersion}/cors/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
],
];
25 changes: 25 additions & 0 deletions tests/lib/Controller/SettingsController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

use OCA\Notifications\ResponseDefinitions;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\Attribute\CORS;
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
use OCP\AppFramework\Http\Attribute\OpenAPI;
use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired;
Expand Down Expand Up @@ -571,4 +572,28 @@ public function objectDefaults(array $empty = [], array $values = ['key' => 'val
public function whitespace(int $value): DataResponse {
return new DataResponse();
}

/**
* Route with CORS annotation
*
* @CORS
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
*
* 200: OK
*/
public function withCorsAnnotation(): DataResponse {
return new DataResponse();
}

/**
* Route with CORS attribute
*
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
*
* 200: OK
*/
#[CORS]
public function withCorsAttribute(): DataResponse {
return new DataResponse();
}
}
138 changes: 138 additions & 0 deletions tests/openapi-administration.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4500,6 +4500,144 @@
}
}
},
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/annotation": {
"post": {
"operationId": "settings-with-cors-annotation",
"summary": "Route with CORS annotation",
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
"tags": [
"settings"
],
"security": [
{
"basic_auth": []
}
],
"parameters": [
{
"name": "apiVersion",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"v2"
],
"default": "v2"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"description": "Required to be true for the API request to pass",
"required": true,
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/attribute": {
"post": {
"operationId": "settings-with-cors-attribute",
"summary": "Route with CORS attribute",
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
"tags": [
"settings"
],
"security": [
{
"basic_auth": []
}
],
"parameters": [
{
"name": "apiVersion",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"v2"
],
"default": "v2"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"description": "Required to be true for the API request to pass",
"required": true,
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/tests/attribute-ocs/{param}": {
"get": {
"operationId": "routing-attributeocs-route",
Expand Down
138 changes: 138 additions & 0 deletions tests/openapi-full.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4650,6 +4650,144 @@
}
}
},
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/annotation": {
"post": {
"operationId": "settings-with-cors-annotation",
"summary": "Route with CORS annotation",
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
"tags": [
"settings"
],
"security": [
{
"basic_auth": []
}
],
"parameters": [
{
"name": "apiVersion",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"v2"
],
"default": "v2"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"description": "Required to be true for the API request to pass",
"required": true,
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/attribute": {
"post": {
"operationId": "settings-with-cors-attribute",
"summary": "Route with CORS attribute",
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
"tags": [
"settings"
],
"security": [
{
"basic_auth": []
}
],
"parameters": [
{
"name": "apiVersion",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"v2"
],
"default": "v2"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"description": "Required to be true for the API request to pass",
"required": true,
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/tests/attribute-ocs/{param}": {
"get": {
"operationId": "routing-attributeocs-route",
Expand Down

0 comments on commit 1312938

Please sign in to comment.