README

Pre-release — Architecture by senior tech lead, implementation largely AI-assisted with human review. Not fully reviewed. Architecture may change before v1.0.0.

Laravel bridge for the DanDoeTech OpenAPI generator. Provides an Artisan command to export OpenAPI 3.1 specs from the Resource Registry.

Installation

composer require dandoetech/laravel-openapi-generator

The service provider is auto-discovered. Publish the config:

php artisan vendor:publish --tag=ddt-openapi-config

Requires dandoetech/laravel-resource-registry.

Quick Start

Export the spec:

php artisan openapi:export

This generates an OpenAPI 3.1 JSON file at storage/app/openapi.json (configurable).

Override title or version:

php artisan openapi:export --title="Catalog API" --oaversion="2.0.0"
php artisan openapi:export --output="public/openapi.json"

What Gets Generated

Every registered resource produces:

• GET /{resource} — list endpoint
• POST /{resource} — create endpoint
• GET /{resource}/{id} — show endpoint
• A component schema with all fields and computed fields

Example output (abbreviated):

{
  "openapi": "3.1.0",
  "info": { "title": "API", "version": "1.0.0" },
  "servers": [{ "url": "http://localhost/api", "description": "Primary API" }],
  "paths": {
    "/product": {
      "get": { "summary": "List Product" },
      "post": { "summary": "Create Product" }
    },
    "/product/{id}": {
      "get": { "summary": "Fetch Product" }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "price": { "type": "number", "format": "double" },
          "category_name": { "type": "string" }
        },
        "required": ["name", "price"]
      },
      "ProblemJson": { "..." : "..." }
    }
  }
}

Computed fields (like category_name) appear in schemas as regular properties. Error responses use the RFC 7807 ProblemJson schema.

Configuration

config/ddt_openapi.php:

return [
    // OpenAPI info block
    'title'   => env('OPENAPI_TITLE', 'API'),
    'version' => env('OPENAPI_VERSION', '1.0.0'),

    // Output path relative to storage_path()
    'output'  => env('OPENAPI_OUTPUT', 'app/openapi.json'),
];

The server URL is built from config('app.url') and the API prefix from config('ddt_api.prefix') (configured in laravel-generic-api).

Programmatic Use

Generate the spec in code:

use DanDoeTech\LaravelOpenApiGenerator\Services\OpenApiGenerator;

$generator = app(OpenApiGenerator::class);
$spec = $generator->create(); // array

return response()->json($spec);

API Overview

Testing

composer install
composer test        # PHPUnit (Orchestra Testbench)
composer qa          # cs:check + phpstan + test

License

MIT