README

请确保已全局安装 Composer，具体安装方法请参考 Composer 文档中的安装章节。

使用 Symfony Flex 的应用程序

打开命令行控制台，进入您的项目目录并执行

$ composer require nicksun/openapi-bundle

未使用 Symfony Flex 的应用程序

步骤 1：下载 Bundle

打开命令行控制台，进入您的项目目录并执行以下命令以下载此 Bundle 的最新稳定版本

$ composer require nicksun/openapi-bundle

步骤 2：启用 Bundle

然后，通过将其添加到项目 config/bundles.php 文件中已注册的 Bundle 列表来启用 Bundle

// config/bundles.php

return [
    // ...
    NickSun\OpenApi\OpenApiBundle::class => ['all' => true],
];

用法

启用路由

// config/routes/open_api.yaml

_open_api:
  resource: '@OpenApiBundle/Resources/config/routing.yaml'

之后检查 /api/doc 端点。

更新 Bundle 参数（可选）

检查https://cdnjs.com/libraries/swagger-ui 以获取最新的 swagger ui 版本。

// config/packages/open_api.yaml

open_api:
  definitions_dir: openapi
  swagger_ui_version: 3.46.0
  title: My Site

在配置文件夹中创建定义目录并放置您的 yaml 文件。

使用OpenAPI 规范来定义您的 API 端点。明智地组织您的文件夹结构。

openapi
├── anchor
│   ├── response.yaml
│   └── schemas.yaml
├── book
│   ├── paths.yaml
│   └── schemas.yaml
├── openapi.yaml
└── user
    ├── paths.yaml
    └── schemas.yaml

限制

只有当 yaml 锚在顶级根文档级别（不带缩进）上定义时，您才能使用不同文件中定义的 yaml 锚。

// openapi/anchor/schemas.yaml

components:
  schemas:
    ApiProblemValidation:
      type: object
      description: Validation error
      properties:
        invalid-params:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Error name
                example: email
              reason:
                type: string
                description: Error reason
                example: Invalid email
        type:
          type: string
          example: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
        title:
          type: string
          example: Validation error
        status:
          type: integer
          format: int64
          description: HTTP status code
          example: 400
        detail:
          type: string
          example: Validation error
        code:
          type: integer
          format: int64
          description: Error code
          example: 12
        instance:
          type: string
          example: /users

// openapi/anchor/response.yaml

400Validation: &400Validation
  400:
    description: Bad request
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ApiProblemValidation'

// openapi/user/paths.yaml

paths:
  /users:
    post:
      tags:
        - user
      description: Create new user.
      summary: Create new user.
      requestBody:
        description: User to add to the system.
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/UserCreate'
      security:
        - Bearer: []
      responses:
        201:
          description: User created.
        <<: *400Validation

nicksun / openapi-bundle

维护者

详情