Skip to content

Commit

Permalink
Endpoint URL params for OpenAPI
Browse files Browse the repository at this point in the history
  • Loading branch information
@tcox-enrollfirst
tcox-enrollfirst committed Feb 9, 2024
1 parent c520156 commit 319192d
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 90 deletions.
85 changes: 41 additions & 44 deletions src/Writing/OpenAPISpecWriter.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,50 +98,6 @@ protected function generatePathsSpec(array $groupedEndpoints)

$pathItem = $operations;

// Placing all URL parameters at the path level, since it's the same path anyway
if (count($endpoints[0]->urlParameters)) {
$parameters = [];
/**
* @var string $name
* @var Parameter $details
*/
foreach ($endpoints[0]->urlParameters as $name => $details) {
$parameterData = [
'in' => 'path',
'name' => $name,
'description' => $details->description,
'example' => $details->example,
// Currently, OAS requires path parameters to be required
'required' => true,
'schema' => [
'type' => $details->type,
],
];
// Workaround for optional parameters
if (empty($details->required)) {
$parameterData['description'] = rtrim('Optional parameter. ' . $parameterData['description']);
$parameterData['examples'] = [
'omitted' => [
'summary' => 'When the value is omitted',
'value' => '',
],
];

if ($parameterData['example'] !== null) {
$parameterData['examples']['present'] = [
'summary' => 'When the value is present',
'value' => $parameterData['example'],
];
}

// Can't have `example` and `examples`
unset($parameterData['example']);
}
$parameters[] = $parameterData;
}
$pathItem['parameters'] = $parameters; // @phpstan-ignore-line
}

return [$path => $pathItem];
})->toArray();
}
Expand All @@ -157,6 +113,47 @@ protected function generateEndpointParametersSpec(OutputEndpointData $endpoint):
{
$parameters = [];

if (count($endpoint->urlParameters)) {
/**
* @var string $name
* @var Parameter $details
*/
foreach ($endpoint->urlParameters as $name => $details) {
$parameterData = [
'in' => 'path',
'name' => $name,
'description' => $details->description,
'example' => $details->example,
// Currently, OAS requires path parameters to be required
'required' => true,
'schema' => [
'type' => $details->type,
],
];
// Workaround for optional parameters
if (empty($details->required)) {
$parameterData['description'] = rtrim('Optional parameter. ' . $parameterData['description']);
$parameterData['examples'] = [
'omitted' => [
'summary' => 'When the value is omitted',
'value' => '',
],
];

if ($parameterData['example'] !== null) {
$parameterData['examples']['present'] = [
'summary' => 'When the value is present',
'value' => $parameterData['example'],
];
}

// Can't have `example` and `examples`
unset($parameterData['example']);
}
$parameters[] = $parameterData;
}
}

if (count($endpoint->queryParameters)) {
/**
* @var string $name
Expand Down
83 changes: 41 additions & 42 deletions tests/Fixtures/openapi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,47 @@ paths:
description: ''
operationId: getApiEchoesUrlParametersParamParam2Param3Param4
parameters:
-
in: path
name: param
description: ''
example: '4'
required: true
schema:
type: string
-
in: path
name: param2
description: ''
required: true
schema:
type: string
example: consequatur
-
in: path
name: param3
description: 'Optional parameter.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: consequatur
-
in: path
name: param4
description: 'Optional parameter.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
-
in: query
name: something
Expand Down Expand Up @@ -219,48 +260,6 @@ paths:
tags:
- Other😎
security: []
parameters:
-
in: path
name: param
description: ''
example: '4'
required: true
schema:
type: string
-
in: path
name: param2
description: ''
required: true
schema:
type: string
example: consequatur
-
in: path
name: param3
description: 'Optional parameter.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: consequatur
-
in: path
name: param4
description: 'Optional parameter.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
/api/withBodyParametersAsArray:
post:
summary: 'Endpoint with body parameters as array.'
Expand Down
9 changes: 5 additions & 4 deletions tests/Unit/OpenAPISpecWriterTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ public function adds_authentication_details_correctly_as_security_info()
}

/** @test */
public function adds_url_parameters_correctly_as_parameters_on_path_item_object()
public function adds_url_parameters_correctly_as_parameters_on_operation_object()
{
$endpointData1 = $this->createMockEndpointData([
'httpMethods' => ['POST'],
Expand All @@ -153,15 +153,16 @@ public function adds_url_parameters_correctly_as_parameters_on_path_item_object(
$results = $this->generate($groups);

$this->assertArrayNotHasKey('parameters', $results['paths']['/path1']);
$this->assertCount(2, $results['paths']['/path1/{param}/{optionalParam}']['parameters']);
$this->assertArrayNotHasKey('parameters', $results['paths']['/path1/{param}/{optionalParam}']);
$this->assertCount(2, $results['paths']['/path1/{param}/{optionalParam}']['post']['parameters']);
$this->assertEquals([
'in' => 'path',
'required' => true,
'name' => 'param',
'description' => 'Something',
'example' => 56,
'schema' => ['type' => 'integer'],
], $results['paths']['/path1/{param}/{optionalParam}']['parameters'][0]);
], $results['paths']['/path1/{param}/{optionalParam}']['post']['parameters'][0]);
$this->assertEquals([
'in' => 'path',
'required' => true,
Expand All @@ -173,7 +174,7 @@ public function adds_url_parameters_correctly_as_parameters_on_path_item_object(
'summary' => 'When the value is present', 'value' => '69'],
],
'schema' => ['type' => 'string'],
], $results['paths']['/path1/{param}/{optionalParam}']['parameters'][1]);
], $results['paths']['/path1/{param}/{optionalParam}']['post']['parameters'][1]);
}

/** @test */
Expand Down

0 comments on commit 319192d

Please sign in to comment.