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:

    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:

use Lacebox\Sole\ApiDocGenerator;

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

Or simply run:

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 LaceboxShoelaceApiDocInterface, you can supply richer details:

<?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:

# List all registered routes
php lace route list

# Generate or update your OpenAPI spec
php lace route docs

After running docs, you’ll see:

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.