php-solution/swagger-ui-gen

Extra functionality for generate Swagger specification

v4.3.3 2020-02-11 08:29 UTC

Requires

• php: ~7.1
• ext-json: *
• symfony/config: >=3.4
• symfony/console: >=3.4
• symfony/dependency-injection: >=3.4
• symfony/doctrine-bridge: >=3.4
• symfony/finder: >=3.4
• symfony/framework-bundle: >=3.4
• symfony/http-foundation: >=3.4
• symfony/routing: >=3.4
• symfony/templating: >=3.4
• symfony/validator: >=3.4
• symfony/yaml: >=3.4

Requires (Dev)

• phpunit/phpunit: ~6.0
• symfony/form: >=3.4
• symfony/var-dumper: >=3.4

Suggests

• doctrine/orm: For using Doctrine ORM OpenApi Schema Handler
• symfony/form: For using Symfony form type OpenApi Operation Handler
• symfony/serializer: For using Symfony serializer OpenApi Operation Handler
• symfony/validator: For using Symfony validator OpenApi Schema Handler

MIT

• Oleksandr Savchenko

README

At now this lib is under development.

SwaggerUIGenerator

This lib includes components and Symfony bundle for generate OpenApi specification.

Install

Via Composer

$ composer require php-solution/swagger-ui-gen

Integration to Project

1. Copy to web document root swagger-ui dist files

2. Copy to /web/assets/swagger

   • index.html
   • swagger-ui.css
   • swagger-ui.js
   • swagger-ui-bundle.js
   • swagger-ui-standalone-preset.js

3. Change on index.html url to swagger openapi specification

const ui = SwaggerUIBundle({
    url: "http://localhost/assets/swagger-spec.json",
})

Add Symfony Configuration

swagger_ui_gen:
    options_provider:
        defaults:
            - '%kernel.root_dir%/Resources/swagger-doc/defaults.yml'
        files:
            - '%kernel.root_dir%/Resources/swagger-doc/general.yml'
            - '%kernel.root_dir%/Resources/swagger-doc/tags.yml'
            - '%kernel.root_dir%/Resources/swagger-doc/paths.yml'
            - '%kernel.root_dir%/Resources/swagger-doc/security_def.yml'
            - '%kernel.root_dir%/Resources/swagger-doc/definitions.yml'
        folders:
            - '@ProjectAdminBundle/Resources/config/swagger-doc'
    handlers:
        validator: false
        form: false
        form_validator: false
        serializer: false
        doctrine_orm: false
    naming_strategy_service: 'PhpSolution\SwaggerUIGen\Bundle\ModelHandler\PropertyNaming\UnderscoreNamingStrategy'

Generate file with Swagger Specification

php bin\console swagger-gen:generate-spec --path=./web/assets/swagger-spec.json

Examples

Symfony project

See example of Symfony app files on /examples/project.

Debug mode for Symfony

1. Add route to your general route.yml

_swagger_ui_gen:
    resource: '@SwaggerUIGenBundle/Resources/config/routing.yml'

1. Add to swagger ui bootstrap html file(index.html):

<script>
window.onload = function() {
function getUrlParameter(name) {
      name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
      var regex = new RegExp('[\\?&]' + name + '=([^&#]*)');
      var results = regex.exec(location.search);
      return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' '));
  }
  const debugDataUrl = getUrlParameter('url');
  const ui = SwaggerUIBundle({
    url: debugDataUrl ? debugDataUrl : "./data.json",
    
    ...
</script>

1. Use on browser:

http://localhost/path-to-swagger-ui-bootstrap-html.html?url=/swagger-ui-gen/data.json

1. See dumped data

http://localhost/swagger-ui-gen/dump

Example of symfony route specification

sf_route_paths:
  -
    route: 'get_list_of_entity' # symfony route name, required
    tags: ['admin'] # openapi tags, not required, default value: []
    schemes: [] # openapi schemes, not required, default value: []
    response: # use for openapi operation response, not required, default value: []
      status_code: 200 # not required, default value: "default"
      type: 'object' # not required, default value: "object", complex values: ['array', 'object', 'collection']
      mapping:
        type: ['doctrine', 'serializer'] # not required, use all if builders empty
        class: 'Project\AdminBundle\Lib\PaginatedCollection' # required
        serializer_groups: ['list'] # use only for serializer
      properties:
        items: # property name, require
          type: 'collection'
          mapping: {class: 'Project\AdminBundle\Entity\Admin'}
    openapi_params: # not required, default value: []
      get:
        summary: 'Get admin list'
        responses:
          << : *defaultResponceErrors
        security:
          - api_key: []
  -
    route: 'post_with_form_dto'
    tags: ['admin']
    request:
      form_class: 'Project\AdminBundle\Form\Type\AdminCreateType'
      form_options: {validation_groups: ['create']}
      validation_class: 'Project\AdminBundle\Lib\AdminModel'
      validation_groups: ['create']
    response:
      type: 'object'
      mapping:
        type: ['doctrine', 'serializer']
        class: 'Project\AdminBundle\Entity\Admin'
        serializer_groups: ['get']
  -
    route: 'post_with_form_multiple_dto'
    tags: ['admin']
    request:
      form_class: 'Project\AdminBundle\Form\Type\MultipleAdminType'
      in: 'body' # use this option if you want to send data as json
    response:
      type: 'collection'
      openapi_params: {$ref: '#/definitions/Admin'}

Example of definition specification

sf_object_definitions:
  - name: 'Admin'
    mapping:
      type: ['doctrine', 'serializer']
      class: 'Project\AdminBundle\Entity\Admin'
  - name: 'AdminCreate'
    type: 'object'
    mapping:
      type: ['validator']
      validation_groups: ['create']
      class: 'Project\AdminBundle\Lib\AdminListModel' # Some DTO
    properties:
      admins:
        type: 'collection'
        mapping: {class: 'Project\AdminBundle\Lib\AdminModel'}
    openapi_params:
      properties:
        email: {uniqueItems: true}

TODO:

1. Use SF Configuration component as normalizer for DefinitionsBuilder, RoutePaths
2. JMSSerializer Schema builder
3. Tests