Adding x-mill-path-aliased and x-mill-path-aliases to OpenAPI specs.

resources/examples/Showtimes/compiled/1.0/openapi/api.yaml

@@ -50,6 +50,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -203,6 +204,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  /theaters:

resources/examples/Showtimes/compiled/1.0/openapi/tags/Movies.yaml

@@ -48,6 +48,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -201,6 +202,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
 components:

resources/examples/Showtimes/compiled/1.1.1/openapi/api.yaml

@@ -50,6 +50,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -219,6 +220,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1.1/openapi/tags/Movies.yaml

@@ -48,6 +48,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -217,6 +218,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1.2/openapi/api.yaml

@@ -50,6 +50,7 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -219,6 +220,8 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1.2/openapi/tags/Movies.yaml

@@ -48,6 +48,7 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -217,6 +218,8 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1.3/openapi/api.yaml

@@ -50,6 +50,7 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -221,6 +222,8 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1.3/openapi/tags/Movies.yaml

@@ -48,6 +48,7 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -219,6 +220,8 @@ paths:
  application/mill.example.movie+json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1/openapi/api.yaml

@@ -50,6 +50,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -219,6 +220,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

resources/examples/Showtimes/compiled/1.1/openapi/tags/Movies.yaml

@@ -48,6 +48,7 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliased: true
  x-mill-path-template: /movie/+id
  /movies:
  get:
@@ -217,6 +218,8 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/error'
+ x-mill-path-aliases:
+ - '/movie/{id}'
  x-mill-path-template: /movies/+id
  x-mill-visibility-private: true
  patch:

src/Compiler.php

@@ -105,13 +105,6 @@ protected function parseResources(): array
  continue;
  }
 
- $is_aliased = $path->isAliased();
-
- // We're always going to be compiling documentation for this path, regardless if it's an alias or
- // not, so let's strip any awareness of that.
- $path->setAliased(false);
- $path->setAliases([]);
-
  $resource_label = $annotations['label'];
  if (!isset($resources[$group]['resources'][$resource_label])) {
  $resources[$group]['resources'][$resource_label] = [
@@ -137,7 +130,7 @@ protected function parseResources(): array
  $action->setPathParams($params);
  $action->filterAnnotationsForVisibility($this->load_private_docs, $this->load_vendor_tag_docs);
 
- if ($is_aliased) {
+ if ($path->isAliased()) {
  $action->incrementOperationId(++$aliases);
  }
 

src/Compiler/Specification/OpenApi.php

@@ -7,6 +7,7 @@
 use Mill\Parser\Annotations\DataAnnotation;
 use Mill\Parser\Annotations\ErrorAnnotation;
 use Mill\Parser\Annotations\ParamAnnotation;
+use Mill\Parser\Annotations\PathAnnotation;
 use Mill\Parser\Annotations\PathParamAnnotation;
 use Mill\Parser\Annotations\QueryParamAnnotation;
 use Mill\Parser\Annotations\ReturnAnnotation;
@@ -97,34 +98,27 @@ public function compile(): array
  'parameters' => $this->processParameters($action),
  'requestBody' => $this->processRequest($action),
  'responses' => $this->processResponses($action),
- 'security' => $this->processSecurity($action),
- 'x-mill-path-template' => $path->getPath(),
- 'x-mill-vendor-tags' => $this->processVendorTags($action),
- 'x-mill-visibility-private' => $path->isVisible()
+ 'security' => $this->processSecurity($action)
  ];
 
+ $schema += $this->processExtensions($action, $path);
+
  foreach ([
+ 'deprecated',
  'description',
  'parameters',
  'requestBody',
  'security',
- 'x-mill-vendor-tags'
+ 'x-mill-path-aliased',
+ 'x-mill-path-aliases',
+ 'x-mill-vendor-tags',
+ 'x-mill-visibility-private'
  ] as $key) {
  if (empty($schema[$key])) {
  unset($schema[$key]);
  }
  }
 
- // Only include the `deprecated` tag if the action is deprecated.
- if (!$schema['deprecated']) {
- unset($schema['deprecated']);
- }
-
- // Only include the `x-mill-visibility-private` tag if the action is private.
- if (!$schema['x-mill-visibility-private']) {
- unset($schema['x-mill-visibility-private']);
- }
-
  $specification['paths'][$identifier][$method] = $schema;
  }
  }
@@ -437,6 +431,29 @@ protected function processSecurity(Action\Documentation $action): array
  ];
  }
 
+ /**
+ * @param Action\Documentation $action
+ * @param PathAnnotation $path
+ * @return array
+ */
+ protected function processExtensions(Action\Documentation $action, PathAnnotation $path): array
+ {
+ $schema = [
+ 'x-mill-path-aliased' => $path->isAliased(),
+ 'x-mill-path-aliases' => array_map(
+ function (PathAnnotation $alias): string {
+ return $alias->getCleanPath();
+ },
+ $path->getAliases()
+ ),
+ 'x-mill-path-template' => $path->getPath(),
+ 'x-mill-vendor-tags' => $this->processVendorTags($action),
+ 'x-mill-visibility-private' => $path->isVisible()
+ ];
+
+ return $schema;
+ }
+
  /**
  * @param Action\Documentation $action
  * @return array

src/Parser/Resource/Action/Documentation.php

@@ -414,13 +414,17 @@ public function getPath(): PathAnnotation
  }
 
  if (empty($paths)) {
- throw new \Exception(
- sprintf(
- 'There were zero non-aliased paths detected in this %s::%s.',
- $this->getClass(),
- $this->getMethod()
- )
- );
+ if (count($this->getPaths()) > 1) {
+ throw new \Exception(
+ sprintf(
+ 'There were zero non-aliased paths detected in this %s::%s.',
+ $this->getClass(),
+ $this->getMethod()
+ )
+ );
+ }
+
+ $paths = $this->getPaths();
  }
 
  return array_shift($paths);