README

🧰 openapi-toolbox

OpenAPI Toolbox是一个便捷的包，包含了我们在一些 @blumilksoftware 项目中使用的重要文档相关功能。

安装

通过Composer安装包并发布配置文件

composer require blumilksoftware/openapi-toolbox
php artisan vendor:publish

如果您只需要内部开发（不提供文档服务），您可以使用开发标志来安装它

composer require blumilksoftware/openapi-toolbox --dev
php artisan vendor:publish

配置

在运行php artisan vendor:publish命令后，配置文件应发布到您的应用程序中。它应该看起来像下面这样

return [
    "format" => Format::YmlToJson,
    "specification" => [
        "path" => resource_path("openapi"),
        "index" => "openapi.yml",
        "allow_multiple_files" => false,
    ],
    "cache" => [
        "enabled" => false,
        "documentation_path" => storage_path("framework/cache/openapi"),
        "checksum_path" => storage_path("framework/cache/openapi.md5"),
    ],
    "ui" => [
        "enabled" => false,
        "single_source" => false,
        "title" => "Documentation",
        "routing" => [
            "prefix" => "documentation",
            "name" => "documentation",
            "middlewares" => [],
        ],
        "provider" => UIProvider::Elements,
        "providers" => [
            "elements" => [
                "script" => [
                    "src" => "https://unpkg.com/@stoplight/elements@7.7.16/web-components.min.js",
                    "sri" => "sha384-bwBnouovwwSJc5fWe7VFNxRg+T2lPHhUcHIzdf7mFfqTZkYtM3T/ehzfEr8F02yY",
                ],
                "stylesheet" => [
                    "href" => "https://unpkg.com/@stoplight/elements@7.7.16/styles.min.css",
                    "sri" => "sha384-1lLf7J28IOR7k5RlItk6Y+G3hDgVB3y4RCgWNq6ZSwjYfvJXPtZAdW0uklsAZbGW",
                ],
            ],
            "swagger" => [
                "script" => [
                    "src" => "https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js",
                    "sri" => "sha384-xy3YXp34ftsoHshRtcUFjOl/M22B5OEHD5S9AjtVzQokz+BxNff8vNW08msKmH46",
                ],
                "stylesheet" => [
                    "href" => "https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css",
                    "sri" => "sha384-pzdBB6iZwPIzBHgXle+9cgvKuMgtWNrBopXkjrWnKCi3m4uJsPPdLQ4IPMqRDirS",
                ],
            ],
        ],
    ],
];

功能

OpenAPI文档UI

通过配置openapi_toolbox.ui.enabled = true，将构建一个文档UI，该UI由可配置的路径和可配置的路由提供服务。目前，仅通过openapi_toolbox.ui.provider设置可配置的UI基础组件有Stoplight Elements和Swagger UI。

默认情况下，它应该可在GET /documentation下访问。

通过将配置变量openapi_toolbox.ui.single_source更改为true，应用程序将提供已经构建的单个源文件用于GUI。

OpenAPI文档端点

提供文档本身可能很复杂，特别是如果规范是由多个嵌套文件构建的。在这里，OpenAPI规范文件将根据配置构建，默认情况下，结果应可在GET /documentation/raw下访问。

OpenAPI规范验证

OpenAPI规范文件将根据配置构建，并通过运行Artisan命令按需进行验证

php artisan openapi:validate

使用示例是将其命令添加到CI管道以用于打开的拉取请求。

针对OpenAPI规范测试请求和响应

基于kirschbaum-development/laravel-openapi-validator，为选定的PHPUnit测试用例添加了特殊特质，使得可以针对应用程序的OpenAPI规范进行验证

use \Blumilk\OpenApiToolbox\OpenApiCompatibility\OpenApiCompatibility;

每次在测试期间执行任何HTTP调用到应用程序时，都会执行额外的验证，并检查请求和响应的结构是否与OpenAPI规范一致。对于特殊情况（例如测试无效请求），可以使用$this->withoutRequestValidation()和$this->withoutResponseValidation()来禁用此验证。

通过配置openapi_toolbox.cache.enabled = true，内部构建器将使用缓存的OpenAPI规范。

blumilksoftware / openapi-toolbox

维护者

详细信息