README

OpenAPI specification generator and interactive documentation UI for the Tempest framework.

Requirements

PHP 8.4+
Tempest framework v2.0

Installation

composer require jdifool/tempest-openapi-tools

Features

Generate OpenAPI specification from PHP code annotations using zircote/swagger-php
Serve OpenAPI spec dynamically via HTTP endpoint
Interactive API documentation with Swagger UI or Scalar

Usage

Command Line

Generate an OpenAPI specification file:

./tempest openapi:generate
./tempest openapi:generate --path=src --output=public/openapi.json

HTTP Endpoints

The package registers two routes (configurable):

Route	Description
`/documentation/openapi.json`	OpenAPI specification (JSON)
`/documentation/openapi`	Interactive API documentation UI

Configuration

Create openapi.config.php in your project:

<?php

use Jdifool\Tempest\Openapi\Config\OpenApiConfig;
use Jdifool\Tempest\Openapi\Config\OpenApiUiTool;

return new OpenApiConfig(
    scanPath: 'app',                                    // Directory to scan for annotations
    routePath: '/documentation/openapi.json',           // OpenAPI spec endpoint
    outputFile: 'openapi.json',                         // Output file for CLI command
    uiTool: OpenApiUiTool::Scalar,                      // UI tool: Scalar or SwaggerUi
    uiRoutePath: '/documentation/openapi',              // UI endpoint
    uiTitle: 'API Documentation',                       // Page title
    enabled: true,                                      // Enable OpenAPI spec endpoint
    uiEnabled: true,                                    // Enable documentation UI endpoint
);

Note: Both enabled and uiEnabled default to false. The endpoints return 404 until explicitly enabled.

Adding OpenAPI Annotations

Use swagger-php attributes in your controllers:

<?php

use OpenApi\Attributes as OA;

#[OA\Info(title: 'My API', version: '1.0.0')]
class MyController
{
    #[OA\Get(path: '/users', summary: 'List users')]
    #[OA\Response(response: 200, description: 'Success')]
    public function index(): Response
    {
        // ...
    }
}

Custom UI Renderer

Implement the OpenApiUiRenderer interface to add a custom documentation UI:

<?php

use Jdifool\Tempest\Openapi\Ui\OpenApiUiRenderer;

class MyCustomRenderer implements OpenApiUiRenderer
{
    public function render(string $specUrl, string $title): string
    {
        return <<<HTML
        <!DOCTYPE html>
        <html>
            <!-- Your custom UI -->
        </html>
        HTML;
    }
}

Custom Route Attributes

This package provides custom Tempest route attributes that read their paths from OpenApiConfig:

Attribute	Description
`#[OpenApiSpecRoute]`	Route for OpenAPI JSON specification
`#[OpenApiUiRoute]`	Route for interactive documentation UI

You can use these attributes in your own controllers if needed:

<?php

use Jdifool\Tempest\Openapi\Routes\OpenApiSpecRoute;
use Tempest\Http\Response;

class MyController
{
    #[OpenApiSpecRoute]
    public function openapi(): Response
    {
        // Custom OpenAPI handling
    }
}

The attributes implement Tempest\Router\Route and resolve their URIs from OpenApiConfig at discovery time.

License

MIT

jdifool/tempest-openapi-tools

包简介

README 文档