README

kleijnweb/swagger-bundle 开发工具

基于 Swagger 文档的 Doctrine 实体、控制器和访问控制文件生成器。

安装

$ composer require cethyworks-swagger-tools-bundle

需要配置 kleijnweb/swagger-bundle。

命令

Doctrine 实体生成器

$ app/console swagger:generate:entities swagger.yml HelloApiBundle

此命令自动根据 Swagger 文件资源定义生成 doctrine 实体。

生成的实体包含 @ORM\ & @Assert\ 注解（@see 支持的 Swagger 属性以下）。

有关更多信息，请参阅 swagger:generate:entities --help。

Id

id 属性强制转换为 guid 格式和 UUID 策略。

关系

生成器不支持关系。

控制器生成器

$ app/console swagger:generate:controllers swagger.yml HelloApiBundle

此命令自动根据 Swagger 文件路径定义生成控制器类（以及相应的控制器测试类），并将它们作为服务注册（由 kleijnweb/swagger-bundle 需要的）。

生成的类包含所有声明的方法，并匹配由 kleijnweb/swagger-bundle 生成的路由。

工作原理（内部行为）

• 列出 sf2 路由（需要 SwaggerBundle 运行）
• 从路由中提取 ^swagger.{documentName}.{resource}.*.{action}$
• 构建 {resource}Controller.php 并包含 {action(s)} 方法
• 注册 swagger.controller.{resource} 服务

有关更多信息，请参阅 swagger:generate:controllers --help。

基于角色的访问控制配置生成器

$ app/console swagger:generate:access-control swagger.yml HelloApiBundle

此命令自动根据 Swagger 文件路径/安全定义生成访问控制配置文件，并将它们注册到 config/security.yml。

有关更多信息，请参阅 swagger:generate:access-control --help。

支持的 Swagger 属性

• readOnly
• required* (Assert)
• x-required* (Assert)
• minLength/maxLength (Assert)
• minimum/maximum (Assert)
• minItems/maxItems (Assert)
• enum (Assert)
• type (Assert)
• pattern (Assert)
• format{date*,date-time*,email,uuid,url, custom*}* (Assert)
• x-parent*
• x-exclude*
• x-serializer-exclude*
• x-unique*

required & x-required

required 在 KleijnWeb\SwaggerBundle\Test\ApiTestCase 中的 Swagger 验证器中使用，x-required 仅由生成器使用。

必需属性定义为根级别的数组，例如

definitions:
  User:
    type: object
    required: ['firstName', 'lastName']
    x-required: ['id']
    properties:
      id:
        type: string
      firstName:
        type: string
      email:
      	type: string
      comment: 
      	type: string
      	format: text

format

Swagger 允许将任何字符串用作格式值，请使用它来添加您的自定义约束。

示例： format: "AppBundle\Validator\Constraints\MyCustomConstraint"

type: string & format: text

生成器将 type: string w/ format: text 识别为 doctrine 类型 text。

x-parent

自定义 Swagger 属性，提供声明生成的实体父类的方法。

x-repository

自定义 Swagger 属性，提供声明生成的实体 doctrine 仓库类的方法。

x-exclude

自定义 Swagger 属性；生成器将忽略具有 x-exclude: false 的定义。

x-serializer-exclude

自定义 Swagger 属性；生成器将在实体中设置 @exclude，供序列化程序使用。

x-unique

自定义 Swagger 属性；生成器将在 @UniqueEntity 中设置此属性。

待办事项

• 处理 one2one 关系
• 处理 many2many 关系
• 处理一些基本行为（可计时）
• 在 put/post&delete 上添加 Request $request（或检测如果 paramType 为 body）
• exclude.yml 文件
• -f/--force 替代 -f=true
• 使用 allOf 处理 Swagger 继承

许可证

MIT 许可证

灵感来源

KleijnWeb\SwaggerBundle & KleijnWeb\SwaggerBundleTools