cethyworks/swagger-tools-bundle

Doctrine entities, controllers & access-control file generators based on Swagger documents.

dev-master 2016-04-14 14:19 UTC

Requires

• php: >=5.4
• doctrine/common: ^2.4
• kleijnweb/swagger-bundle: dev-apiTestCaseSupportQuery
• sensio/generator-bundle: ~3.0
• symfony/config: ^2.8
• symfony/console: ^2.8
• symfony/dependency-injection: ^2.8
• symfony/http-kernel: ^2.8
• symfony/routing: ^2.8

MIT

• Cethy

README

Development tools for kleijnweb/swagger-bundle

Doctrine entities, controllers & access-control file generators based on Swagger documents.

Install

$ composer require cethyworks-swagger-tools-bundle

Needs kleijnweb/swagger-bundle to be configured.

Commands

Doctrine Entities Generator

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

This command auto-generate doctrine entities based on Swagger file resource definitions.

The resulting entities contains @ORM\ & @Assert\ annotations (@see Supported Swagger Properties below).

See swagger:generate:entities --help for more details.

Id

The id attribute is forced to a guid format & UUID strategy.

Relations

The generator does not support relations.

Controllers Generator

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

This command auto-generate Controller classes (and corresponding ControllerTest classes) based on the Swagger file paths definitions and register them as services (as needed by kleijnweb/swagger-bundle).

The resultant classes contains all the methods declared and matches the routing generated by kleijnweb/swagger-bundle.

How it works (internal behavior) :

• lists sf2 routes (needs SwaggerBundle working)
• extracts ^swagger.{documentName}.{resource}.*.{action}$ from routes
• build {resource}Controller.php with {action(s)} methods
• register swagger.controller.{resource} service

See swagger:generate:controllers --help for more details.

Role Based Access Control Configuration Generator

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

This command auto-generate access-control configuration files based on the Swagger file paths/security definitions and register them in config/security.yml.

See swagger:generate:access-control --help for more details.

Supported Swagger Properties

• 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 is used by the swagger validator in KleijnWeb\SwaggerBundle\Test\ApiTestCase, x-required is only used by the generator.

Required properties are defined as an array & at the root level, eg :

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 allow any string as format's value, Use it to add your custom Constraints.

example : format: "AppBundle\Validator\Constraints\MyCustomConstraint"

type: string & format: text

The generator recognize type: string w/ format: text as a doctrine type text.

x-parent

Custom swagger property providing the means to declare a parent class to the entity generated.

x-repository

Custom swagger property providing the means to declare a doctrine repository class to the entity generated.

x-exclude

Custom swagger property ; The generator will ignore definitions with x-exclude: false.

x-serializer-exclude

Custom swagger property ; The generator will set a @exclude in the entity for the Serializer.

x-unique

Custom swagger property ; The generator will set this property into @UniqueEntity.

Todo

• Handle one2one relations
• Handle many2many relations
• Handle some basic behavior (timestampable)
• Add Request $request on put/post&delete (or detect if paramType body)
• exclude.yml file
• -f/--force instead of -f=true
• handle Swagger inheritance with allOf

License

MIT License

Inspiration

KleijnWeb\SwaggerBundle & KleijnWeb\SwaggerBundleTools