包简介

OpenAPI tools for Tempest PHP.

README 文档

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 适用场景与选型建议

jdifool/tempest-openapi-tools 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 2 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 12 月 25 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 jdifool/tempest-openapi-tools 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 jdifool/tempest-openapi-tools 我们能提供哪些服务？

定制开发 / 二次开发

基于 jdifool/tempest-openapi-tools 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

jdifool/tempest-openapi-tools

包简介