Skip to content

Commit 86a07bf

Browse files
provokateurinprovokateurin
authored
Merge pull request #203 from nextcloud/feat/controllermethod/cors-documentation
feat(ControllerMethod): Add documentation for CORS endpoints
2 parents 3794c04 + 1312938 commit 86a07bf

File tree

6 files changed

+317
-2
lines changed

6 files changed

+317
-2
lines changed

‎generate-spec.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,7 @@
452452
$isIgnored = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'IgnoreOpenAPI');
453453
$isPasswordConfirmation = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'PasswordConfirmationRequired');
454454
$isExApp = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'ExAppRequired');
455+
$isCORS = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'CORS');
455456
$scopes = Helpers::getOpenAPIAttributeScopes($classMethod, $routeName);
456457

457458
if ($isIgnored) {
@@ -505,7 +506,7 @@
505506
];
506507
}
507508

508-
$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isAdmin, $isDeprecated, $isPasswordConfirmation);
509+
$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isAdmin, $isDeprecated, $isPasswordConfirmation, $isCORS);
509510
if ($classMethodInfo->returns !== []) {
510511
Logger::error($routeName, 'Returns an invalid response');
511512
continue;

‎src/ControllerMethod.php‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,14 @@ public function __construct(
3434
) {
3535
}
3636

37-
public static function parse(string $context, array $definitions, ClassMethod $method, bool $isAdmin, bool $isDeprecated, bool $isPasswordConfirmation): ControllerMethod {
37+
public static function parse(string $context,
38+
array $definitions,
39+
ClassMethod $method,
40+
bool $isAdmin,
41+
bool $isDeprecated,
42+
bool $isPasswordConfirmation,
43+
bool $isCORS,
44+
): ControllerMethod {
3845
global $phpDocParser, $lexer, $allowMissingDocs;
3946

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

220+
if ($isCORS) {
221+
$methodDescription[] = 'This endpoint allows CORS requests';
222+
}
223+
213224
if (count($methodDescription) == 1) {
214225
$methodSummary = $methodDescription[0];
215226
$methodDescription = [];

‎tests/appinfo/routes.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,5 +74,7 @@
7474
['name' => 'Settings#parameterRequestBody', 'url' => '/api/{apiVersion}/parameterPATCH', 'verb' => 'PATCH', 'postfix' => 'PATCH', 'requirements' => ['apiVersion' => '(v2)']],
7575
['name' => 'Settings#objectDefaults', 'url' => '/api/{apiVersion}/objectDefaults', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
7676
['name' => 'Settings#whitespace', 'url' => '/api/{apiVersion}/whitespace', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
77+
['name' => 'Settings#withCorsAnnotation', 'url' => '/api/{apiVersion}/cors/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
78+
['name' => 'Settings#withCorsAttribute', 'url' => '/api/{apiVersion}/cors/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
7779
],
7880
];

‎tests/lib/Controller/SettingsController.php‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
use OCA\Notifications\ResponseDefinitions;
1313
use OCP\AppFramework\Http;
14+
use OCP\AppFramework\Http\Attribute\CORS;
1415
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
1516
use OCP\AppFramework\Http\Attribute\OpenAPI;
1617
use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired;
@@ -571,4 +572,28 @@ public function objectDefaults(array $empty = [], array $values = ['key' => 'val
571572
public function whitespace(int $value): DataResponse {
572573
return new DataResponse();
573574
}
575+
576+
/**
577+
* Route with CORS annotation
578+
*
579+
* @CORS
580+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
581+
*
582+
* 200: OK
583+
*/
584+
public function withCorsAnnotation(): DataResponse {
585+
return new DataResponse();
586+
}
587+
588+
/**
589+
* Route with CORS attribute
590+
*
591+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
592+
*
593+
* 200: OK
594+
*/
595+
#[CORS]
596+
public function withCorsAttribute(): DataResponse {
597+
return new DataResponse();
598+
}
574599
}

‎tests/openapi-administration.json‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4500,6 +4500,144 @@
45004500
}
45014501
}
45024502
},
4503+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/annotation": {
4504+
"post": {
4505+
"operationId": "settings-with-cors-annotation",
4506+
"summary": "Route with CORS annotation",
4507+
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
4508+
"tags": [
4509+
"settings"
4510+
],
4511+
"security": [
4512+
{
4513+
"basic_auth": []
4514+
}
4515+
],
4516+
"parameters": [
4517+
{
4518+
"name": "apiVersion",
4519+
"in": "path",
4520+
"required": true,
4521+
"schema": {
4522+
"type": "string",
4523+
"enum": [
4524+
"v2"
4525+
],
4526+
"default": "v2"
4527+
}
4528+
},
4529+
{
4530+
"name": "OCS-APIRequest",
4531+
"in": "header",
4532+
"description": "Required to be true for the API request to pass",
4533+
"required": true,
4534+
"schema": {
4535+
"type": "boolean",
4536+
"default": true
4537+
}
4538+
}
4539+
],
4540+
"responses": {
4541+
"200": {
4542+
"description": "OK",
4543+
"content": {
4544+
"application/json": {
4545+
"schema": {
4546+
"type": "object",
4547+
"required": [
4548+
"ocs"
4549+
],
4550+
"properties": {
4551+
"ocs": {
4552+
"type": "object",
4553+
"required": [
4554+
"meta",
4555+
"data"
4556+
],
4557+
"properties": {
4558+
"meta": {
4559+
"$ref": "#/components/schemas/OCSMeta"
4560+
},
4561+
"data": {}
4562+
}
4563+
}
4564+
}
4565+
}
4566+
}
4567+
}
4568+
}
4569+
}
4570+
}
4571+
},
4572+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/attribute": {
4573+
"post": {
4574+
"operationId": "settings-with-cors-attribute",
4575+
"summary": "Route with CORS attribute",
4576+
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
4577+
"tags": [
4578+
"settings"
4579+
],
4580+
"security": [
4581+
{
4582+
"basic_auth": []
4583+
}
4584+
],
4585+
"parameters": [
4586+
{
4587+
"name": "apiVersion",
4588+
"in": "path",
4589+
"required": true,
4590+
"schema": {
4591+
"type": "string",
4592+
"enum": [
4593+
"v2"
4594+
],
4595+
"default": "v2"
4596+
}
4597+
},
4598+
{
4599+
"name": "OCS-APIRequest",
4600+
"in": "header",
4601+
"description": "Required to be true for the API request to pass",
4602+
"required": true,
4603+
"schema": {
4604+
"type": "boolean",
4605+
"default": true
4606+
}
4607+
}
4608+
],
4609+
"responses": {
4610+
"200": {
4611+
"description": "OK",
4612+
"content": {
4613+
"application/json": {
4614+
"schema": {
4615+
"type": "object",
4616+
"required": [
4617+
"ocs"
4618+
],
4619+
"properties": {
4620+
"ocs": {
4621+
"type": "object",
4622+
"required": [
4623+
"meta",
4624+
"data"
4625+
],
4626+
"properties": {
4627+
"meta": {
4628+
"$ref": "#/components/schemas/OCSMeta"
4629+
},
4630+
"data": {}
4631+
}
4632+
}
4633+
}
4634+
}
4635+
}
4636+
}
4637+
}
4638+
}
4639+
}
4640+
},
45034641
"/ocs/v2.php/tests/attribute-ocs/{param}": {
45044642
"get": {
45054643
"operationId": "routing-attributeocs-route",

‎tests/openapi-full.json‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4650,6 +4650,144 @@
46504650
}
46514651
}
46524652
},
4653+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/annotation": {
4654+
"post": {
4655+
"operationId": "settings-with-cors-annotation",
4656+
"summary": "Route with CORS annotation",
4657+
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
4658+
"tags": [
4659+
"settings"
4660+
],
4661+
"security": [
4662+
{
4663+
"basic_auth": []
4664+
}
4665+
],
4666+
"parameters": [
4667+
{
4668+
"name": "apiVersion",
4669+
"in": "path",
4670+
"required": true,
4671+
"schema": {
4672+
"type": "string",
4673+
"enum": [
4674+
"v2"
4675+
],
4676+
"default": "v2"
4677+
}
4678+
},
4679+
{
4680+
"name": "OCS-APIRequest",
4681+
"in": "header",
4682+
"description": "Required to be true for the API request to pass",
4683+
"required": true,
4684+
"schema": {
4685+
"type": "boolean",
4686+
"default": true
4687+
}
4688+
}
4689+
],
4690+
"responses": {
4691+
"200": {
4692+
"description": "OK",
4693+
"content": {
4694+
"application/json": {
4695+
"schema": {
4696+
"type": "object",
4697+
"required": [
4698+
"ocs"
4699+
],
4700+
"properties": {
4701+
"ocs": {
4702+
"type": "object",
4703+
"required": [
4704+
"meta",
4705+
"data"
4706+
],
4707+
"properties": {
4708+
"meta": {
4709+
"$ref": "#/components/schemas/OCSMeta"
4710+
},
4711+
"data": {}
4712+
}
4713+
}
4714+
}
4715+
}
4716+
}
4717+
}
4718+
}
4719+
}
4720+
}
4721+
},
4722+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/cors/attribute": {
4723+
"post": {
4724+
"operationId": "settings-with-cors-attribute",
4725+
"summary": "Route with CORS attribute",
4726+
"description": "This endpoint requires admin access\nThis endpoint allows CORS requests",
4727+
"tags": [
4728+
"settings"
4729+
],
4730+
"security": [
4731+
{
4732+
"basic_auth": []
4733+
}
4734+
],
4735+
"parameters": [
4736+
{
4737+
"name": "apiVersion",
4738+
"in": "path",
4739+
"required": true,
4740+
"schema": {
4741+
"type": "string",
4742+
"enum": [
4743+
"v2"
4744+
],
4745+
"default": "v2"
4746+
}
4747+
},
4748+
{
4749+
"name": "OCS-APIRequest",
4750+
"in": "header",
4751+
"description": "Required to be true for the API request to pass",
4752+
"required": true,
4753+
"schema": {
4754+
"type": "boolean",
4755+
"default": true
4756+
}
4757+
}
4758+
],
4759+
"responses": {
4760+
"200": {
4761+
"description": "OK",
4762+
"content": {
4763+
"application/json": {
4764+
"schema": {
4765+
"type": "object",
4766+
"required": [
4767+
"ocs"
4768+
],
4769+
"properties": {
4770+
"ocs": {
4771+
"type": "object",
4772+
"required": [
4773+
"meta",
4774+
"data"
4775+
],
4776+
"properties": {
4777+
"meta": {
4778+
"$ref": "#/components/schemas/OCSMeta"
4779+
},
4780+
"data": {}
4781+
}
4782+
}
4783+
}
4784+
}
4785+
}
4786+
}
4787+
}
4788+
}
4789+
}
4790+
},
46534791
"/ocs/v2.php/tests/attribute-ocs/{param}": {
46544792
"get": {
46554793
"operationId": "routing-attributeocs-route",

0 commit comments

Comments
 (0)