README

此包通过使用您的 OpenAPI YAML 文件来提供解析后的 Swagger 文档。

入门指南

安装

composer require chriha/laravel-api-documentation

规范路径

默认情况下，OpenAPI YAML 规范应该位于 ./resources/api/... 中。在此目录中，您可以创建每个版本的文件，例如 v1.yml、v2.yml、v3.yml 等。

API 版本信息

每个版本（文件）将提供一个端点（例如 v1.yml 导致 /api/v1），其中包含在 info 键下指定的所有信息。

...
info:
  version: "v1.0.1"
  title: "Awesome API"
  contact:
    email: "awesome@api.info.com"
...

... 将导致以下响应体

{
    "version": "v1.0.1",
    "title": "Awesome API",
    "contact": {
        "email": "awesome@api.info.com"
    }
}

文档

将通过 URI /docs/api/[VERSION] 和文件 /docs/api/[VERSION]/file 提供。

配置

如果您想更改默认配置，可以发布并更新以满足您的需求。

php artisan vendor:publish --provider="Chriha\ApiDocumentation\ApiDocumentationServiceProvider"

配置将随后在 ./config/api-documentation.php 中可用。

规范路径和命名格式

您可以通过配置中的 specifications 键更改规范的路径和文件的格式。

更改中间件

默认情况下，文档使用 web 中间件，API 信息端点使用 api 中间件。您可以通过更改配置中的 middleware 键来更改此设置。

隐藏信息

如果您想从信息端点（例如 /api/v1）隐藏密钥，您可以通过在配置中的 specifications.hide 下使用 "点" 表示法指定这些密钥。

    'specifications' => [
        'hide'   => [
            'v1' => [
                'contact.email',
                'description',
            ]
        ],
    ],

开发

常规提交

如果您提交合并请求，请使用常规提交以实现自动化语义版本控制。

干运行语义发布

npm i @semantic-release/changelog @semantic-release/git @semantic-release/exec -D
GITHUB_TOKEN=YOUR_GITHUB_TOKEN npx semantic-release --dry-run --no-ci

贡献

有关行为准则和提交拉取请求的过程的详细信息，请参阅 CONTRIBUTING.md。