README

此包允许您使用 NelmioApiDocBundle 并将所有 API 文档存储在 yml 配置文件中。

包包括 2 个新的 API 文档提取器

• 链式提取器
• Yaml 提取器。

包现在更改了标准 API 文档提取器的定义，现在为 PhpSolution\NelmioApiDocYamlBundle\Extractor\ChainApiDocExtractor 的 @nelmio_api_doc.extractor.api_doc_extractor 定义。

您可以使用标准 ApiDocExtractor，使用 @nelmio_api_doc.extractor.api_doc_extractor.phpdoc 服务名称。

链式提取器使用 Yaml 提取器和 phpdoc 提取器。

Yaml 提取器会检查所有 @Bundle\Resources\config\api_doc.yml 并为 API 创建配置。

所有配置参数您可以在 https://github.com/nelmio/NelmioApiDocBundle 文档中找到。

使用方法

yml 配置示例

rest_api_security_login_check: # route name
    section: "Authorization"
    resource: false
    description: ""
    https: false
    deprecated: false
    tags: []
    filters: []
    output:
        class: PhpSolution\NelmioApiDocYamlBundle\Form\SimpleType
        options:
            fields:
                - {name: "token",  type: "text"}
                - {name: "expDate",  type: "integer", options: {description: "timestamp"}}
                - {name: "expDateOffset",  type: "integer", options: {description: "time offset"}}
    requirements:
        - { name: "username",  dataType: "string"}
        - { name: "password",  dataType: "string"}
    statusCodes: {"200": "Returned when successful", 401: "Returned when the user is not authorized"}
    views: []
    documentation: 'Get authorization token for access to api endpoints'
    authentication: true

如果您想定义输入选项而不创建新的类来存储 API 文档，可以使用以下方法

requirements:
    - { name: "username",  dataType: "string"}
    - { name: "password",  dataType: "string"}

如果您想定义输出参数而不创建新的类来存储 API 文档，可以使用以下方法

output:
    class: PhpSolution\NelmioApiDocYamlBundle\Form\SimpleType
    options:
        fields:
            - {name: "token",  type: "text"}
            - {name: "expDate",  type: "integer", options: {description: "timestamp"}}
            - {name: "expDateOffset",  type: "integer", options: {description: "time offset"}}

配置

1. 将路由添加到 app/config/routing.yml

NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /rest-api/doc 

1. 如果您想更改包的默认设置，可以在 app/config/config.yml 中进行更改

    ...
    nelmio_api_doc_yaml:
        metadata:
            file_path: api_doc.yml
            defaults: ~ #path to defaults
        cache:
            enabled: false
            file: %kernel.cache_dir%/api-doc-yml.cache

安装

1. 在 composer.json 中添加

    "require": {
        ...
        "php-solution/nelmio-apidoc-yaml-bundle": "dev-master"
        ...
    }

1. 在 AppKernel.php 中添加

    public function registerBundles()
    {
        $bundles = array(
        ...
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        new PhpSolution\NelmioApiDocYamlBundle\CiklumNelmioApiDocYamlBundle(),
        ...

1. 运行

    composer update php-solution/nelmio-apidoc-yaml-bundle

待办事项

• 覆盖率超过 80%