README

此捆绑包可用于修改 API-Platform 生成的 OpenAPI 文档。

安装

您可以使用以下命令将此捆绑包添加到您的项目中：composer require linku/api-documentation-bundle。Symfony flex 应自动将捆绑包添加到项目中使用的捆绑包列表。如果不这样做，请将 Linku\ApiDocumentationBundle\LinkuApiDocumentationBundle::class => ['all' => true], 添加到 config/bundles.php 文件中。

目前，您需要手动添加一个 config/packages/linku_api_documentation.yaml 文件，并将您的项目配置放在那里。示例配置可在 此文件末尾 找到。

您还需要添加以下路由

linku_api_documentation:
    resource: "@LinkuApiDocumentationBundle/Resources/routing/sections.xml"

可选地，您可以为生成的所有路径添加一个 prefix: 前缀。这应该与 API-Platform 在其路由中使用的相同前缀。

部分

在 sections 配置中，您可以定义可用部分的列表。列表中使用的标识符也可以用于定义 API-Platform 资源或端点的部分。

每个部分都有一个 prefix（URI 路径前缀）和一个 title。

使用原始的 /docs 路由将显示在 default_section 中定义的默认部分。您可以使用 /{section_prefix}/docs 查看其他部分的文档。

默认用法

默认情况下，所有以部分的前缀 prefix 开头的自定义定义路径的端点都将添加到该部分。例如，具有 prefix: 'customer_portal' 的部分将自动包含所有以 /customer_portal/ 开头的自定义路径的端点。

基于资源

在 API-Platform 配置中，您可以将一个 sections 数组添加到资源的 attributes 中。然后，此资源中的所有端点都将添加到具有这些标识符的部分。

YAML 示例

resources:
    App\Task\Task:
        extraProperties:
            sections: ['customerPortal']

基于端点

在 API-Platform 配置中，您可以将一个 sections 数组添加到端点定义中。然后，该端点将添加到具有那些标识符的部分。

YAML 示例

resources:
    App\Task\Task:
        operations:
            ApiPlatform\Metadata\Get:
                extraProperties:
                    sections: ['customerPortal']

删除

开箱即用，API-Platform 不允许您删除查询参数或响应，而无需手动定义所有剩余的参数。因为您只能添加或覆盖项，但不能完全删除它们。此捆绑包提供了一些帮助，以从生成的文档中删除响应和参数。

参数

要删除参数，需要端点 path 和 method。以及参数的 name。这些可以添加到 linku_api_documentation.removal.parameters 列表中。

请求体

要删除请求体，需要端点 path 和 method。这些可以添加到 linku_api_documentation.removal.request_bodies 列表中。

响应

要删除响应，需要端点 path 和 method。以及响应的 statusCode。这些可以添加到 linku_api_documentation.removal.responses 列表中。

配置示例

linku_api_documentation:
    sections:
        default:
            prefix: ''
            title: ''
        customerPortal:
            prefix: 'customer_portal'
            title: 'Customer Portal'
    default_section: 'default'

    removal:
        parameters:
            - path: '/users/me'
              method: 'get'
              name: 'uuid'

        request_bodies:
            - path: '/tasks/{id}/complete'
              method: 'put'

        responses:
            - path: '/users/update_credentials'
              method: 'post'
              statusCode: 201
            - path: '/users/update_credentials'
              method: 'post'
              statusCode: 422