README

目前这个库正在开发中。

SwaggerUIGenerator

这个库包含用于生成 OpenApi 规范的组件和 Symfony 扩展包。

安装

通过 Composer

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

集成到项目中

1. 将 swagger-ui dist 文件 复制到网站文档根目录

2. 复制到 /web/assets/swagger

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

3. 将 index.html 的 URL 修改为 Swagger OpenApi 规范

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

添加 Symfony 配置

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'

生成包含 Swagger 规范的文件

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

示例

Symfony 项目

在 /examples/project 下查看 Symfony 应用文件示例。

Symfony 的调试模式

1. 将路由添加到 general route.yml 中

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

1. 将内容添加到 swagger ui bootstrap html 文件（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. 在浏览器中使用

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

1. 查看输出的数据

https:///swagger-ui-gen/dump

symfony 路由规范示例

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'}

定义规范示例

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}

待办事项

1. 使用 SF 配置组件作为 DefinitionsBuilder 和 RoutePaths 的规范器
2. JMSSerializer Schema 构建器
3. 测试