API Doc Generator
=================

Automatically generating up-to-date API documentation saves you from writing and maintaining Swagger/OpenAPI files by hand. LacePHP’s **ApiDocGenerator** inspects your routes and controller specs, outputs an OpenAPI JSON, and the **Docs** endpoint renders it with Swagger UI.

Why API Docs Matter
-------------------
- **Self-documenting**: Clients see exactly what endpoints, parameters and responses are available  
- **Consistency**: Docs stay in sync with your code—no stale manual edits  
- **Onboarding**: New team members (or external consumers) can explore your API interactively  

Exposing the Swagger UI
-----------------------
LacePHP includes a `Docs` controller that serves the Swagger UI:

1. **Generate** the JSON spec file:
   
   .. code-block:: bash

      php lace route docs

   This command writes `openapi.json` to `public/outsole/docs/openapi.json`.

2. **Browse** to `http://your-app/lace/docs` to see the interactive Swagger UI.

LacePHP automatically pulls in CSS/JS from `public/outsole/swagger-ui/`, and initialises the UI.

Generating the OpenAPI Spec
---------------------------

LacePHP’s `ApiDocGenerator` can build your spec from the router:

.. code-block:: php

   use Lacebox\Sole\ApiDocGenerator;

   $generator = new ApiDocGenerator($router);
   $generator->toJsonFile(__DIR__ . '/../../public/outsole/docs/openapi.json');

Or simply run:

.. code-block:: bash

   php lace route docs

By default it includes every route’s HTTP method, path and a basic 200 response.  

Adding Controller-Level Details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If your controller implements `Lacebox\Shoelace\ApiDocInterface`, you can supply richer details:

.. code-block:: php

   <?php
   namespace Weave\Controllers;

   use Lacebox\Shoelace\ApiDocInterface;

   class PostController implements ApiDocInterface
   {
       public static function openApiSpec(): array
       {
           return [
             '/posts' => [
               'get' => [
                 'summary'    => 'List all posts',
                 'parameters' => [
                   [
                     'name'     => 'page',
                     'in'       => 'query',
                     'required' => false,
                     'schema'   => ['type'=>'integer','default'=>1]
                   ]
                 ],
                 'responses'  => [
                   '200' => [
                     'description'=>'Array of post objects',
                     'content'    => [
                       'application/json' => [
                         'schema'=>[
                           'type'=>'array',
                           'items'=>['$ref'=>'#/components/schemas/Post']
                         ]
                       ]
                     ]
                   ]
                 ]
               ]
             ]
           ];
       }
   }

When `ApiDocGenerator::generate()` sees `PostController::openApiSpec()`, it merges your custom spec into the generated document.

CLI Integration
---------------

The built-in `RouteCommand` handles both listing and docs:

.. code-block:: bash

   # List all registered routes
   php lace route list

   # Generate or update your OpenAPI spec
   php lace route docs

After running `docs`, you’ll see:

.. code-block:: text

   OpenAPI docs generated at: public/outsole/docs/openapi.json

Best Practices
--------------

- **Tag routes**: use `tags` in your `openApiSpec()` to group endpoints by controller or feature.  
- **Define schemas**: add reusable `components/schemas` for request and response bodies.  
- **Keep examples clear**: include `example` or `examples` fields so clients know what to send and expect.  
- **Version your API**: include `version` in `info` and adjust your base path or servers accordingly.  


.. warning::

   - The generator includes every route by default—exclude internal or debug endpoints manually.  
   - Ensure `public/outsole/swagger-ui` assets are in place (CSS/JS) or the UI won’t load.  
   - Do not expose sensitive endpoints (e.g. admin tools) in your public docs—use route guards or separate environments.  

With LacePHP’s API Doc Generator and Swagger UI, you can maintain accurate, interactive documentation effortlessly—making integration a breeze for everyone.

|
|