最新消息:文章中包含代码时,请遵守代码高亮规范!

symfony中使用NelmioApiDocBundle进行API管理【原创】

PHP Pota 882浏览 0评论

项目开发对接过程中,在使用postman编写API之前都是使用API.html表格式的静态页作为API的载体,此方法在编写的时候麻烦不说,后续若是出现API修改文档维护上也比较麻烦,而且在对接过程中接口无法直接测试访问查看返回数据是否正确,导致一系列的麻烦出现,使用postman作为载体后虽然在测试以及描述上方便不少但在出现API修改还需要单独打开postman进行维护。
NelmioApiDocBundle为Symfony提供了一套很方便的API管理,安装方法:

$ composer require nelmio/api-doc-bundle

如果是项目开发中间安装此Bundle记得清除cache文件夹缓存文件之后再安装不然conposer.json文件无法更新,之后再进行必经的注册Bundle

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        );
        // ...
    }
    // ...
}

之后写入以下配置

# app/config/routing.yml
NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /api/doc

# app/config/config.yml
nelmio_api_doc: ~

当然,因为此Bundle生成页面使用的是twig作为模板引擎,所以需要确保启用twig

# app/config/config.yml
framework:
    templating:
        engines: ['twig']

下面是表达一个API的备注信息,其中

use Nelmio\ApiDocBundle\Annotation\ApiDoc;

为必须声明,为不影响阅读,请点击展开查看

namespace Your\Namespace;

use Nelmio\ApiDocBundle\Annotation\ApiDoc;

class YourController extends Controller
{
    /**
     * API详细说明-
     * 会一直扫描到第一个注释
     *
     * @ApiDoc(
     *  resource=true,
     *  section=false, //此参数用于API分组 =分组名即可默认为false 同分组的API会归类到一起
     *  description="API简单说明",
     *  filters={//过滤参数说明
     *      {"name"="a-filter", "dataType"="integer"},
     *      {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
     *  },
     *  requirements={
     *      {
     *          "name"="limit",
     *          "dataType"="integer",
     *          "requirement"="\d+",
     *          "description"=""
     *      }
     *  },
     *  tags={
     *     "这个是标签",
     *     "设置颜色" = "#000" //标签颜色,可不设置
     * },
     *  parameters={
     *      {"name"="参数1", "dataType"="integer", "required"=true, "format"="['格式']", "description"="描述"}
     *  }
     * )
     */
    public function indexAction()
    {
        var_dump($this->get('request')->request->all());exit;
        return $this->render('ApiBundle:Default:index.html.twig');
    }
}

若当前备注的Action路由可以正常访问到,此时打开之前申请的对应的路由,当前默认地址为/api/doc则可以看到以下页面

以上备注展开信息为:
点击页面上的Sandbox进入砂箱测试

对于此页面的具体设置可以参考官方文档点击查看
使用此Bundle在后期维护Api中节省不少时间不过自带的砂箱测试没有postman来的直接和方便,当然各有各的好处。当然对于线上项目不可能每个API在连接过程中都实时生成,而且也由于当前Bundle的特性导致若Controller较多时会出现较慢和占用内存较多的情况,该Bundle也提供了命令用于生成Api.html静态页,功能和路由生成的一样。

php app/console api:doc:dump --format=html > api.html

此文件会生成在web目录下,外部可直接访问得到方便对接使用

转载时请注明出处及相应链接,本文永久地址:http://blog.it985.com/21336.html


pay_weixin
pay_weixin
微信打赏
pay_weixin
支付宝打赏
感谢您对作者Pota的打赏,我们会更加努力!    如果您想成为作者,请点我

您必须 登录 才能发表评论!