README

此包简化了在YAML或JSON中编写和结构化OpenApi规范的过程。

简介

从注解或从代码自动生成的OpenApi规范非常不错，尤其是在处理较小的API时。但是，当API增长并变得更加复杂时，使用注解很容易变得混乱，最终导致注解比实际代码还多。

此包帮助您编写和结构化在YAML或JSON中编写的OpenApi规范。带有引用部分的规范会被合并到一个单独的规范文件中。此外，该包还附带ReDoc，作为您的文档的用户界面。

安装

要开始使用，请通过composer安装Laravel OpenAPI

composer require brocc/laravel-openapi

您可以选择通过以下方式发布配置文件和视图

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

默认情况下，此包会检查位于base_path('/api-docs/openapi.yaml')的OpenApi规范文件，这可以在配置文件中轻松更改。

要生成规范，请运行以下命令

php artisan openapi:generate

多个规范

您可能有多个规范，例如，一个公开的API和一个内部API，或者甚至多个您希望分离到不同规范中的API版本。

多版本配置的示例。

您可以通过在config/openapi.php中添加额外的文档来轻松生成多个规范。

'documentations'  => [
    'default' => [
        'title' => 'Docs - latest',
        
        // Absolute path to the main OpenAPI specification.
        'spec'  => base_path('api-docs/v2/openapi.yaml'),

        'routes' => [
            // Route for accessing documentation UI.
            'ui'         => '/docs',

            // Route to OpenAPI specification file, can be json or yaml.
            'openapi'    => '/openapi/v2/openapi.json',

            // Middleware to be applied on the ui and docs, eg. api, auth, trusted_proxies etc.
            'middleware' => [
                'ui'      => [],
                'openapi' => [],
            ],
        ],
    ],
    'v1' => [
        'title' => 'Docs - v1',

        'spec'  => base_path('api-docs/v1/openapi.yaml'),

        'routes' => [
            'ui'         => '/docs/v1',

            'openapi'    => '/openapi/v1/openapi.json',

            'middleware' => [
                'ui'      => [],
                'openapi' => [],
            ],
        ],
    ],
],

这将生成两个文档，分别可在浏览器的/docs和/docs/v1访问，规范在/openapi/v2/openapi.json和/openapi/v1/openapi.json访问。

您可以通过在openapi:generate命令中指定文档来轻松选择只发布一个规范

php artisan openapi:generate v1

开发

在开发过程中，您可能希望每次规范发生变化时都看到更新的文档。这可以通过将generate_always设置为true来实现。建议在生产环境中将其设置为false。

贡献

欢迎任何形式的贡献！

我们接受通过Github上的Pull Requests进行的贡献。