refactor: Use convenience methods

Author: tymondesigns

README.md

@@ -55,7 +55,7 @@ $openApi = OpenApi::create()
                     ->operationId('users.show')
                     ->tags('Users')
                     ->responses(
-                        Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/User'))),
+                        Response::ok()->content(MediaType::json(Reference::schema('User'))),
                         Response::notFound(),
                     ),
             ),

docs/openapi/components.mdx

@@ -61,20 +61,20 @@ $components = Components::create()
     ));
 ```
 
-Reference schemas anywhere with `Reference::to()`:
+Reference schemas anywhere with typed `Reference` shortcuts:
 
 ```php
 use Cortex\OpenApi\Objects\Reference;
 
 // In a MediaType
-MediaType::json(Reference::to('#/components/schemas/User'))
+MediaType::json(Reference::schema('User'))
 
 // In a Parameter schema slot
-Parameter::query('filter', Reference::to('#/components/schemas/Filter'))
+Parameter::query('filter', Reference::schema('Filter'))
 
 // In a composed schema (allOf/oneOf/anyOf)
 Schema::object()->allOf(
-    Reference::to('#/components/schemas/BaseEntity'),
+    Reference::schema('BaseEntity'),
     Schema::object()->properties(Schema::string('title')),
 )
 ```
@@ -112,15 +112,15 @@ use Cortex\OpenApi\Objects\PathItem;
 
 PathItem::create('/users/{userId}/articles/{slug}')
     ->parameters(
-        Reference::to('#/components/parameters/UserId'),
-        Reference::to('#/components/parameters/ArticleSlug'),
+        Reference::parameter('UserId'),
+        Reference::parameter('ArticleSlug'),
     )
     ->operations(
         Operation::get()
             ->operationId('users.articles.show')
             ->parameters(
-                Reference::to('#/components/parameters/PageSize'),
-                Reference::to('#/components/parameters/PageNumber'),
+                Reference::parameter('PageSize'),
+                Reference::parameter('PageNumber'),
             ),
     );
 ```
@@ -133,7 +133,7 @@ Centralize common error responses to avoid repeating them on every operation:
 use Cortex\OpenApi\Objects\Response;
 use Cortex\OpenApi\Objects\MediaType;
 
-$errorSchema = Reference::to('#/components/schemas/Error');
+$errorSchema = Reference::schema('Error');
 
 $components = Components::create()
     ->response('BadRequest',
@@ -158,9 +158,9 @@ Reference them from operations using `Response::ref()`:
 ```php
 Operation::get()
     ->responses(
-        Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/User'))),
-        Response::ref('#/components/responses/NotFound'),
-        Response::ref('#/components/responses/Unauthorized'),
+        Response::ok()->content(MediaType::json(Reference::schema('User'))),
+        Response::ref('NotFound'),
+        Response::ref('Unauthorized'),
     );
 ```
 
@@ -175,17 +175,17 @@ $components = Components::create()
     ->requestBody('CreateUser',
         RequestBody::create()
             ->required(true)
-            ->content(MediaType::json(Reference::to('#/components/schemas/UserInput'))),
+            ->content(MediaType::json(Reference::schema('UserInput'))),
     )
     ->requestBody('UpdateUser',
         RequestBody::create()
             ->required(true)
-            ->content(MediaType::json(Reference::to('#/components/schemas/UserPatch'))),
+            ->content(MediaType::json(Reference::schema('UserPatch'))),
     );
 
 // Reference
-Operation::post()->requestBody(RequestBody::ref('#/components/requestBodies/CreateUser'));
-Operation::patch()->requestBody(RequestBody::ref('#/components/requestBodies/UpdateUser'));
+Operation::post()->requestBody(RequestBody::ref('CreateUser'));
+Operation::patch()->requestBody(RequestBody::ref('UpdateUser'));
 ```
 
 ## Security Schemes
@@ -249,8 +249,8 @@ Reference headers in a response's `->headers()` array:
 
 ```php
 Response::ok()->headers([
-    'X-Request-Id'          => Reference::to('#/components/headers/X-Request-Id'),
-    'X-RateLimit-Remaining' => Reference::to('#/components/headers/X-RateLimit-Remaining'),
+    'X-Request-Id'          => Reference::header('X-Request-Id'),
+    'X-RateLimit-Remaining' => Reference::header('X-RateLimit-Remaining'),
 ])
 ```
 
@@ -283,7 +283,7 @@ $components = Components::create()
                     ->operationId('webhook.user.event')
                     ->requestBody(
                         RequestBody::create()
-                            ->content(MediaType::json(Reference::to('#/components/schemas/UserEvent'))),
+                            ->content(MediaType::json(Reference::schema('UserEvent'))),
                     )
                     ->responses(Response::ok()),
             ),
@@ -328,12 +328,12 @@ $components = Components::create()
     // Shared responses
     ->response('NotFound',
         Response::notFound()->content(
-            MediaType::json(Reference::to('#/components/schemas/Error')),
+            MediaType::json(Reference::schema('Error')),
         ),
     )
     ->response('Unauthorized',
         Response::unauthorized()->content(
-            MediaType::json(Reference::to('#/components/schemas/Error')),
+            MediaType::json(Reference::schema('Error')),
         ),
     )
 

docs/openapi/installation.mdx

@@ -7,7 +7,6 @@ icon: 'terminal'
 ## Requirements
 
 - PHP 8.3+
-- Composer for dependency management
 
 ## Installation
 

docs/openapi/quickstart.mdx

@@ -60,7 +60,7 @@ icon: 'rocket'
 </Step>
 
 <Step title="Define Paths and Operations">
-  Describe your API endpoints with `PathItem` and `Operation`. Use `Reference::to()` to point at component schemas rather than embedding them repeatedly.
+  Describe your API endpoints with `PathItem` and `Operation`. Use typed `Reference` shortcuts to point at component schemas rather than embedding them repeatedly.
 
   ```php
   use Cortex\OpenApi\Objects\PathItem;
@@ -83,10 +83,10 @@ icon: 'rocket'
                   ->responses(
                       Response::ok()
                           ->description('A paged array of pets')
-                          ->content(MediaType::json(Reference::to('#/components/schemas/Pet'))),
+                          ->content(MediaType::json(Reference::schema('Pet'))),
                       Response::default()
                           ->description('Unexpected error')
-                          ->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+                          ->content(MediaType::json(Reference::schema('Error'))),
                   ),
 
               Operation::post()
@@ -95,23 +95,23 @@ icon: 'rocket'
                   ->requestBody(
                       RequestBody::create()
                           ->required(true)
-                          ->content(MediaType::json(Reference::to('#/components/schemas/Pet'))),
+                          ->content(MediaType::json(Reference::schema('Pet'))),
                   )
                   ->responses(
                       Response::created()
-                          ->content(MediaType::json(Reference::to('#/components/schemas/Pet'))),
+                          ->content(MediaType::json(Reference::schema('Pet'))),
                   ),
           ),
 
       PathItem::create('/pets/{petId}')
-          ->parameters(Reference::to('#/components/parameters/PetId'))
+          ->parameters(Reference::parameter('PetId'))
           ->operations(
               Operation::get()
                   ->operationId('showPetById')
                   ->tags('pets')
                   ->responses(
-                      Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/Pet'))),
-                      Response::notFound()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+                      Response::ok()->content(MediaType::json(Reference::schema('Pet'))),
+                      Response::notFound()->content(MediaType::json(Reference::schema('Error'))),
                   ),
           ),
   ];
@@ -260,7 +260,7 @@ Most objects provide named constructors so you rarely need `new`. Here's a quick
 
 ## Working with References
 
-`Reference::to()` creates a `$ref` to any component registered in `Components`. Typed named constructors on `Reference` build the correct pointer automatically — no need to write out the full path.
+Typed named constructors on `Reference` build the correct `$ref` pointer automatically — no need to write out the full path. Use `Reference::to()` as an escape hatch when you need to reference a path outside the standard component buckets.
 
 ```php
 use Cortex\OpenApi\Objects\Reference;
@@ -280,9 +280,9 @@ Reference::pathItem('LegacyPets')     // #/components/pathItems/LegacyPets
 Reference::to('#/components/schemas/Pet')
 
 // Shortcut on the target class (equivalent, and communicates intent)
-Response::ref('#/components/responses/NotFound')
-Parameter::ref('#/components/parameters/PetId')
-RequestBody::ref('#/components/requestBodies/CreateUser')
+Response::ref('NotFound')
+Parameter::ref('PetId')
+RequestBody::ref('CreateUser')
 ```
 
 ## Vendor Extensions

docs/openapi/request-bodies.mdx

@@ -74,7 +74,7 @@ use Cortex\OpenApi\Objects\Reference;
 MediaType::json(Schema::object()->properties(...))
 
 // $ref to a registered component
-MediaType::json(Reference::to('#/components/schemas/User'))
+MediaType::json(Reference::schema('User'))
 
 // Raw PHP array — escape hatch for hand-crafted schemas
 MediaType::json(['type' => 'string', 'format' => 'binary'])
@@ -92,8 +92,8 @@ A single `RequestBody` can declare multiple accepted formats. The client sends t
 RequestBody::create()
     ->required(true)
     ->content(
-        MediaType::json(Reference::to('#/components/schemas/Article')),
-        MediaType::xml(Reference::to('#/components/schemas/Article')),
+        MediaType::json(Reference::schema('Article')),
+        MediaType::xml(Reference::schema('Article')),
     )
 ```
 
@@ -223,7 +223,7 @@ $components = Components::create()
 // Reference from an operation
 Operation::post()
     ->operationId('articles.create')
-    ->requestBody(RequestBody::ref('#/components/requestBodies/CreateArticle'));
+    ->requestBody(RequestBody::ref('CreateArticle'));
 ```
 
 ## Complete Example

docs/openapi/responses.mdx

@@ -154,7 +154,7 @@ Header::create()
 use Cortex\OpenApi\Objects\Link;
 
 Response::created()
-    ->content(MediaType::json(Reference::to('#/components/schemas/Article')))
+    ->content(MediaType::json(Reference::schema('Article')))
     ->links([
         'GetArticleById' => Link::create()
             ->operationId('articles.show')
@@ -199,8 +199,8 @@ $components = Components::create()
 Operation::get()
     ->responses(
         Response::ok()->json($schema),
-        Response::ref('#/components/responses/NotFound'),
-        Response::ref('#/components/responses/Unauthorized'),
+        Response::ref('NotFound'),
+        Response::ref('Unauthorized'),
     );
 ```
 

docs/openapi/webhooks-and-callbacks.mdx

@@ -128,7 +128,7 @@ $components = Components::create()
     ->schema('EventEnvelope', $eventEnvelope)
     ->schema('UserCreatedPayload', Schema::object()
         ->allOf(
-            Reference::to('#/components/schemas/EventEnvelope'),
+            Reference::schema('EventEnvelope'),
             Schema::object()->properties(
                 Schema::object('data')->properties(
                     Schema::integer('id')->required(),
@@ -138,7 +138,7 @@ $components = Components::create()
         ))
     ->schema('OrderPlacedPayload', Schema::object()
         ->allOf(
-            Reference::to('#/components/schemas/EventEnvelope'),
+            Reference::schema('EventEnvelope'),
             Schema::object()->properties(
                 Schema::object('data')->properties(
                     Schema::integer('orderId')->required(),
@@ -153,7 +153,7 @@ $doc->components($components)->webhooks([
             ->operationId('webhook.user.created')
             ->requestBody(
                 RequestBody::create()->content(
-                    MediaType::json(Reference::to('#/components/schemas/UserCreatedPayload')),
+                    MediaType::json(Reference::schema('UserCreatedPayload')),
                 ),
             )
             ->responses(Response::ok()),
@@ -232,7 +232,7 @@ $components = Components::create()
                     Operation::post()
                         ->requestBody(
                             RequestBody::create()
-                                ->content(MediaType::json(Reference::to('#/components/schemas/Event'))),
+                                ->content(MediaType::json(Reference::schema('Event'))),
                         )
                         ->responses(Response::ok()),
                 ),
@@ -243,7 +243,7 @@ $components = Components::create()
 Operation::post()
     ->operationId('hooks.subscribe')
     ->callbacks([
-        'onEvent' => Callback::ref('#/components/callbacks/EventWebhook'),
+        'onEvent' => Callback::ref('EventWebhook'),
     ]);
 ```
 
@@ -283,7 +283,7 @@ $doc = OpenApi::create()
                         Operation::post()
                             ->requestBody(
                                 RequestBody::create()->content(
-                                    MediaType::json(Reference::to('#/components/schemas/Event')),
+                                    MediaType::json(Reference::schema('Event')),
                                 ),
                             )
                             ->responses(Response::ok()),
@@ -299,7 +299,7 @@ $doc = OpenApi::create()
                 ->summary('Payment Succeeded')
                 ->requestBody(
                     RequestBody::create()->content(
-                        MediaType::json(Reference::to('#/components/schemas/Event')),
+                        MediaType::json(Reference::schema('Event')),
                     ),
                 )
                 ->responses(Response::ok()),
@@ -325,7 +325,7 @@ $doc = OpenApi::create()
                 )
                 ->responses(Response::created())
                 ->callbacks([
-                    'onEvent' => Callback::ref('#/components/callbacks/GenericWebhook'),
+                    'onEvent' => Callback::ref('GenericWebhook'),
                 ]),
         ),
     );

src/Objects/Callback.php

@@ -22,9 +22,9 @@ public static function create(): self
         return new self();
     }
 
-    public static function ref(string $pointer): Reference
+    public static function ref(string $name, ?string $summary = null, ?string $description = null): Reference
     {
-        return Reference::to($pointer);
+        return Reference::callback($name, $summary, $description);
     }
 
     public function expression(string $runtimeExpression, PathItem $pathItem): self

src/Objects/Example.php

@@ -29,9 +29,9 @@ public static function create(): self
         return new self();
     }
 
-    public static function ref(string $pointer): Reference
+    public static function ref(string $name, ?string $summary = null, ?string $description = null): Reference
     {
-        return Reference::to($pointer);
+        return Reference::example($name, $summary, $description);
     }
 
     public function summary(?string $summary): self

src/Objects/Header.php

@@ -54,9 +54,9 @@ public static function create(): self
         return new self();
     }
 
-    public static function ref(string $pointer): Reference
+    public static function ref(string $name, ?string $summary = null, ?string $description = null): Reference
     {
-        return Reference::to($pointer);
+        return Reference::header($name, $summary, $description);
     }
 
     public function description(?string $description): self