README

将draw/swagger集成到symfony 4包中

首要目标是让程序员能够以最小的努力生成swagger文档。draw/swagger提供多种提取器来获取所需信息（例如PHP）。

与symfony的集成允许您使用大部分Draw\Swagger\Schema（别名@Swagger）作为控制器方法上的注解来记录它们。

该包还提供了一些工具，可以在不使用FOSRestBundle的情况下提供REST API。

FOSRestBundle集成由DrawSwaggerBundle提供，但将被删除以缩小此包的范围。

配置

以下是一个配置示例

draw_swagger: 
    enableFosRestSupport: null
    enableDoctrineSupport: null #null will auto detect if DoctrineBundle is install and consider it true
    convertQueryParameterToAttribute: false
    responseConverter: false
    definitionAliases:
        - class: App\Entity\MyUser #This will change reference to class App\Entity\MyUser as User in swagger
          alias: User
        - class: App\Entity\ #This will Remove App\Entity\ from namespace so the class name would be expose instead of the FQCN
          alias: ''
        
    schema: #The schema section is not validate but it must match swagger format and will be the starting point of the generated doc
        info:
            title: 'Documentation for Acme API'
            description: 'This is the descriptoin of the 'Acme API'
            termsOfService: 'N\A'
            contact: ~
            version: "5.0"

控制器文档

要记录swagger的控制器，您必须使用@Swagger\Tag或@Swagger\Operation注解。

/**
 * @Swagger\Tag("Acme")
 */
public function defaultAction()
{
   //...
}

/**
 * @Swagger\Operation(
 *     operationId="default",
 *     tags={"Acme"}
 * )
 */
public function defaultAction()
{
   //...
}

如果您计划使用swagger代码生成器，我们建议使用@Swagger\Operation，因为它将为您提供对operationId的控制，否则它将使用路由名称。

查询参数

如果您想在控制器中注入配置的查询参数，您必须在配置中将convertQueryParameterToAttribute设置为true。

draw_swagger:
  convertQueryParameterToAttribute: true

您还必须向控制器添加注解Draw\Swagger\Schema\QueryParameter。这将提供swagger的文档信息并配置应注入哪些查询参数。

/**
 * @Swagger\QueryParameter(name="param1")
 *
 * @param string $param1
 */
public function createAction($param1 = 'default')
{
   //...
}

视图

要允许自动序列化响应，您必须启用它

draw_swagger:
  responseConverter: true

它将检测您的控制器返回值是否不是响应，并根据Draw\SwaggerBundle\View\View注解进行序列化。

默认情况下，如果没有注解，序列化上下文将没有任何值，响应将为200。使用视图可以覆盖序列化组、版本和响应的状态码。视图注解也用于swagger文档，headers属性用于该目的。

如果您的控制器返回null，则默认状态码将设置为204（无内容）。

/**
 * @Draw\SwaggerBundle\View\View(
 *     statusCode=201,
 *     serializerGroups={"MyGroup"},
 *     headers={
 *       "X-Acme-CustomHeader"=@Swagger\Header(type="string", description="The is a custom header")
 *     }
 * )
 */
public function createAction()
{
   //...
}

Draw\SwaggerBundle\View\View继承自Sensio\Bundle\FrameworkExtraBundle\Configuration\Template，因此您可以通过使用$request->attributes->get('_template');以相同的方式访问它。

您不需要在每个头部放置一个serializerVersion，您可以创建一个监听器，它将根据其他内容设置版本。以下是一个示例监听器，它将从URL路径/api/v{number}/....中获取版本。

<?php namespace App\Listener;

use Draw\SwaggerBundle\View\View;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ViewEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class VersionListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
             //It must be after reading __template attribute but before the serializer listener pass
            KernelEvents::VIEW => ['onKernelView', 31] 
        ];
    }

    public function onKernelView(ViewEvent $event)
    {
        $request = $event->getRequest();
        $pathInfo = $request->getPathInfo();

        $sections = explode('/', $pathInfo, 4);

        if(!isset($sections[2])) {
            return;
        }

        $version = trim($sections[2], 'v');

        if($sections[2] != ('v' . $version)) {
            return;
        }

        $view = $request->attributes->get('_template', new View([]));

        if($view instanceof View && is_null($view->getSerializerVersion())) {
            $view->setSerializerVersion($version);
        }

        $request->attributes->set('_template', $view);
    }
}