docs: update all docs for Info::create() signature, json() shortcuts, path(), Reference typed constructors, Style enum, and errors()

Made-with: Cursor

Author: tymondesigns

docs/openapi/info-and-metadata.mdx

@@ -15,9 +15,7 @@ use Cortex\OpenApi\Objects\Info;
 use Cortex\OpenApi\Objects\Contact;
 use Cortex\OpenApi\Objects\License;
 
-$info = Info::create()
-    ->title('Payments API')
-    ->version('2.1.0')
+$info = Info::create('Payments API', '2.1.0')
     ->summary('Handles payment processing and refunds')
     ->description('Full description with **Markdown** support.')
     ->termsOfService('https://example.com/terms')
@@ -208,9 +206,7 @@ use Cortex\OpenApi\Objects\ExternalDocs;
 
 $doc = OpenApi::create()
     ->info(
-        Info::create()
-            ->title('Acme Platform API')
-            ->version('3.0.0')
+        Info::create('Acme Platform API', '3.0.0')
             ->summary('Powers the Acme product suite')
             ->description(<<<'MD'
                 The Acme Platform API provides programmatic access to all Acme services.

docs/openapi/introduction.mdx

@@ -93,7 +93,7 @@ $userSchema = Schema::object()->properties(
 );
 
 $doc = OpenApi::create()
-    ->info(Info::create()->title('Users API')->version('1.0.0'))
+    ->info(Info::create('Users API', '1.0.0'))
     ->servers(Server::create('https://api.example.com'))
     ->paths(
         PathItem::create('/users')->operations(

docs/openapi/paths-and-operations.mdx

@@ -19,7 +19,23 @@ PathItem::create('/articles')
     );
 ```
 
-The path is registered as the key in the document's `paths` map when you pass it to `OpenApi::paths()`.
+Pass path items to `OpenApi::paths()` (auto-keyed from the path string) or add them one at a time with `OpenApi::path()`:
+
+```php
+use Cortex\OpenApi\OpenApi;
+use Cortex\OpenApi\Objects\Reference;
+
+// Variadics — auto-keys from PathItem::getPath()
+OpenApi::create()->paths(
+    PathItem::create('/users'),
+    PathItem::create('/users/{id}'),
+);
+
+// Fluent single-add — also accepts a Reference to a path item component
+OpenApi::create()
+    ->path('/users', PathItem::create('/users'))
+    ->path('/legacy', Reference::pathItem('LegacyUsers'));
+```
 
 ### Path-Level Metadata
 
@@ -174,31 +190,33 @@ Parameter::query('filter', Schema::string())
 
 ### Serialization Style
 
-Control how arrays and objects are serialized in query strings using `->style()` and `->explode()`:
+Control how arrays and objects are serialized in query strings using `->style()` and `->explode()`. Pass the `Style` enum or a plain string.
 
 <Tabs>
 <Tab title="Form (default for query)">
   ```php
+  use Cortex\OpenApi\Enums\Style;
+
   // Default: ?color=blue&color=red (explode=true)
   Parameter::query('color', Schema::array()->items(Schema::string()))
-      ->style('form')
+      ->style(Style::Form)
       ->explode()
 
   // ?color=blue,red (explode=false)
   Parameter::query('color', Schema::array()->items(Schema::string()))
-      ->style('form')
+      ->style(Style::Form)
       ->explode(false)
   ```
 </Tab>
 <Tab title="Space / Pipe Delimited">
   ```php
   // ?color=blue%20red
   Parameter::query('color', Schema::array()->items(Schema::string()))
-      ->style('spaceDelimited')
+      ->style(Style::SpaceDelimited)
 
   // ?color=blue|red
   Parameter::query('color', Schema::array()->items(Schema::string()))
-      ->style('pipeDelimited')
+      ->style(Style::PipeDelimited)
   ```
 </Tab>
 <Tab title="Deep Object">
@@ -207,16 +225,16 @@ Control how arrays and objects are serialized in query strings using `->style()`
   Parameter::query('filter', Schema::object()->properties(
       Schema::string('status'),
       Schema::string('type'),
-  ))->style('deepObject')
+  ))->style(Style::DeepObject)
   ```
 </Tab>
 <Tab title="Path Matrix / Label">
   ```php
   // ;color=blue (matrix)
-  Parameter::path('color', Schema::string())->style('matrix')
+  Parameter::path('color', Schema::string())->style(Style::Matrix)
 
   // .blue (label)
-  Parameter::path('color', Schema::string())->style('label')
+  Parameter::path('color', Schema::string())->style(Style::Label)
   ```
 </Tab>
 </Tabs>
@@ -247,9 +265,8 @@ use Cortex\JsonSchema\Schema;
 use Cortex\OpenApi\Objects\PathItem;
 use Cortex\OpenApi\Objects\Operation;
 use Cortex\OpenApi\Objects\Parameter;
-use Cortex\OpenApi\Objects\Response;
-use Cortex\OpenApi\Objects\MediaType;
 use Cortex\OpenApi\Objects\RequestBody;
+use Cortex\OpenApi\Objects\Response;
 use Cortex\OpenApi\Objects\Reference;
 use Cortex\OpenApi\Objects\ExternalDocs;
 
@@ -266,8 +283,8 @@ PathItem::create('/articles/{slug}')
             ->summary('Get an article')
             ->externalDocs(ExternalDocs::create('https://docs.example.com/articles'))
             ->responses(
-                Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/Article'))),
-                Response::notFound()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+                Response::ok()->json(Reference::schema('Article')),
+                Response::notFound()->json(Reference::schema('Error')),
             ),
 
         Operation::patch()
@@ -276,13 +293,13 @@ PathItem::create('/articles/{slug}')
             ->summary('Update an article')
             ->requestBody(
                 RequestBody::create()
-                    ->required(true)
-                    ->content(MediaType::json(Reference::to('#/components/schemas/ArticleUpdate'))),
+                    ->required()
+                    ->json(Reference::schema('ArticleUpdate')),
             )
             ->responses(
-                Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/Article'))),
-                Response::badRequest()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
-                Response::notFound()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+                Response::ok()->json(Reference::schema('Article')),
+                Response::badRequest()->json(Reference::schema('Error')),
+                Response::notFound()->json(Reference::schema('Error')),
             ),
 
         Operation::delete()
@@ -291,7 +308,7 @@ PathItem::create('/articles/{slug}')
             ->summary('Delete an article')
             ->responses(
                 Response::noContent(),
-                Response::notFound()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+                Response::notFound()->json(Reference::schema('Error')),
             ),
     );
 ```

docs/openapi/quickstart.mdx

@@ -130,9 +130,7 @@ icon: 'rocket'
 
   $doc = OpenApi::create()
       ->info(
-          Info::create()
-              ->title('Petstore API')
-              ->version('1.0.0')
+          Info::create('Petstore API', '1.0.0')
               ->description('A sample Petstore API demonstrating cortexphp/openapi.'),
       )
       ->servers(Server::create('https://petstore.example.com/v1'))
@@ -157,7 +155,8 @@ icon: 'rocket'
   try {
       $doc->validate();
   } catch (ValidationException $e) {
-      echo $e->getMessage();
+      echo $e->getMessage();          // human-readable summary
+      print_r($e->errors());          // structured array of errors keyed by JSON pointer
       exit(1);
   }
 
@@ -261,15 +260,24 @@ 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`. On the target class itself, `ref()` is a type-safe shortcut.
+`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.
 
 ```php
 use Cortex\OpenApi\Objects\Reference;
 
-// Generic reference — works for anything
+// Typed shortcuts — recommended, construct the $ref path automatically
+Reference::schema('Pet')              // #/components/schemas/Pet
+Reference::response('NotFound')       // #/components/responses/NotFound
+Reference::parameter('PetId')         // #/components/parameters/PetId
+Reference::requestBody('CreateUser')  // #/components/requestBodies/CreateUser
+Reference::header('RateLimit')        // #/components/headers/RateLimit
+Reference::securityScheme('OAuth2')   // #/components/securitySchemes/OAuth2
+Reference::link('GetPet')             // #/components/links/GetPet
+Reference::callback('EventWebhook')   // #/components/callbacks/EventWebhook
+Reference::pathItem('LegacyPets')     // #/components/pathItems/LegacyPets
+
+// Generic reference — use when the bucket isn't covered above
 Reference::to('#/components/schemas/Pet')
-Reference::to('#/components/parameters/PetId')
-Reference::to('#/components/responses/NotFound')
 
 // Shortcut on the target class (equivalent, and communicates intent)
 Response::ref('#/components/responses/NotFound')
@@ -283,7 +291,7 @@ All objects support OpenAPI specification extensions via `->x()`. Keys are norma
 
 ```php
 $doc = OpenApi::create()
-    ->info(Info::create()->title('My API')->version('1.0.0'))
+    ->info(Info::create('My API', '1.0.0'))
     ->x('x-api-id', 'my-service-v1')    // prefix already present — used as-is
     ->x('internal-owner', 'platform');   // prefix added automatically → x-internal-owner
 

docs/openapi/request-bodies.mdx

@@ -8,29 +8,39 @@ icon: 'file-up'
 
 `RequestBody` describes the payload an operation expects from the client. Attach it to an operation with `->requestBody()`.
 
+The `->json()` shortcut handles the most common case — a required JSON body — in one call:
+
 ```php
 use Cortex\OpenApi\Objects\RequestBody;
-use Cortex\OpenApi\Objects\MediaType;
+use Cortex\OpenApi\Objects\Reference;
 use Cortex\OpenApi\Objects\Operation;
 use Cortex\JsonSchema\Schema;
 
+// Shortcut — sets application/json content in one step
 Operation::post()
     ->operationId('users.create')
     ->requestBody(
         RequestBody::create()
-            ->required(true)
+            ->required()
             ->description('The new user payload')
-            ->content(
-                MediaType::json(
-                    Schema::object()->properties(
-                        Schema::string('name')->required(),
-                        Schema::string('email')->format('email')->required(),
-                    ),
+            ->json(
+                Schema::object()->properties(
+                    Schema::string('name')->required(),
+                    Schema::string('email')->format('email')->required(),
                 ),
             ),
     );
+
+// With a component reference
+Operation::put()
+    ->operationId('users.update')
+    ->requestBody(
+        RequestBody::create()->required()->json(Reference::schema('UserInput')),
+    );
 ```
 
+For multiple content types or non-JSON bodies, use `->content()` with explicit `MediaType` objects (see [MediaType](#mediatype) below).
+
 ### required
 
 Mark the body required when clients must always send it. Optional bodies (the default) are used for partial updates or endpoints where the payload is situational.
@@ -206,8 +216,8 @@ use Cortex\OpenApi\Objects\Reference;
 $components = Components::create()
     ->requestBody('CreateArticle',
         RequestBody::create()
-            ->required(true)
-            ->content(MediaType::json(Reference::to('#/components/schemas/ArticleInput'))),
+            ->required()
+            ->json(Reference::schema('ArticleInput')),
     );
 
 // Reference from an operation

docs/openapi/responses.mdx

@@ -10,14 +10,13 @@ icon: 'file-down'
 
 ```php
 use Cortex\OpenApi\Objects\Response;
-use Cortex\OpenApi\Objects\MediaType;
 use Cortex\OpenApi\Objects\Reference;
 
 Operation::get()
     ->operationId('users.show')
     ->responses(
-        Response::ok()->content(MediaType::json(Reference::to('#/components/schemas/User'))),
-        Response::notFound()->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+        Response::ok()->json(Reference::schema('User')),
+        Response::notFound()->json(Reference::schema('Error')),
     );
 ```
 
@@ -55,10 +54,10 @@ Response::status(418)  // 418 I'm a Teapot
 ```php
 Operation::get()
     ->responses(
-        Response::ok()->content(MediaType::json($successSchema)),
+        Response::ok()->json($successSchema),
         Response::default()
             ->description('An unexpected error occurred')
-            ->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+            ->json(Reference::schema('Error')),
     );
 ```
 
@@ -68,16 +67,27 @@ Use `Response::default()` to cover all error codes with a single error schema ra
 
 ### Response Content
 
-Attach one or more `MediaType` objects to document the response body:
+Attach one or more `MediaType` objects to document the response body. The `->json()` shortcut handles the common case of a single JSON content type in one call:
+
+```php
+use Cortex\OpenApi\Objects\Reference;
+
+// Shortcut — sets application/json content directly
+Response::ok()->json(Reference::schema('Article'))
+Response::ok()->json(Schema::object()->properties(Schema::string('id')))
+Response::ok()->json()   // no schema — emits an empty application/json entry
+```
+
+For multiple content types or non-JSON responses, use `->content()` with `MediaType`:
 
 ```php
 use Cortex\OpenApi\Objects\MediaType;
 
 Response::ok()
     ->description('The requested resource')
     ->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')),
     )
 ```
 
@@ -179,20 +189,16 @@ use Cortex\OpenApi\Objects\Components;
 
 $components = Components::create()
     ->response('NotFound',
-        Response::notFound()->content(
-            MediaType::json(Reference::to('#/components/schemas/Error')),
-        ),
+        Response::notFound()->json(Reference::schema('Error')),
     )
     ->response('Unauthorized',
-        Response::unauthorized()->content(
-            MediaType::json(Reference::to('#/components/schemas/Error')),
-        ),
+        Response::unauthorized()->json(Reference::schema('Error')),
     );
 
 // Reference from an operation
 Operation::get()
     ->responses(
-        Response::ok()->content(MediaType::json($schema)),
+        Response::ok()->json($schema),
         Response::ref('#/components/responses/NotFound'),
         Response::ref('#/components/responses/Unauthorized'),
     );
@@ -231,7 +237,6 @@ Response::ok()
 ```php
 use Cortex\JsonSchema\Schema;
 use Cortex\OpenApi\Objects\Response;
-use Cortex\OpenApi\Objects\MediaType;
 use Cortex\OpenApi\Objects\Header;
 use Cortex\OpenApi\Objects\Link;
 use Cortex\OpenApi\Objects\Reference;
@@ -253,17 +258,15 @@ Operation::post()
                     ->schema(Schema::string()->format('uri'))
                     ->description('URL of the newly created article'),
             ])
-            ->content(MediaType::json($articleSchema))
+            ->json($articleSchema)
             ->links([
                 'GetArticle' => Link::create()
                     ->operationId('articles.show')
                     ->parameters(['slug' => '$response.body#/slug']),
             ]),
 
-        Response::badRequest()
-            ->content(MediaType::json(Reference::to('#/components/schemas/ValidationError'))),
+        Response::badRequest()->json(Reference::schema('ValidationError')),
 
-        Response::unauthorized()
-            ->content(MediaType::json(Reference::to('#/components/schemas/Error'))),
+        Response::unauthorized()->json(Reference::schema('Error')),
     );
 ```