README

📦 在Symfony应用程序中创建一个Swagger-ui页面（类似于这个）。

描述

如果您正在编写Swagger API规范且它变得过大，您可以将其拆分为多个文件。此捆绑包允许以简单的方式拆分规范文件并生成静态的index.html文件，以便使用Swagger UI。

安装

composer req stfalcon-studio/swagger-bundle

检查config/bundles.php文件

默认情况下，Symfony Flex会将SwaggerBundle添加到config/bundles.php文件中。但在您在捆绑包安装过程中忽略contrib-recipe的情况下，它将不会添加。在这种情况下，请手动添加捆绑包。

# config/bundles.php

return [
    // other bundles
    StfalconStudio\SwaggerBundle\SwaggerBundle::class => ['all' => true],
    // other bundles
];

使用

首先，我们需要设置存储规范的文件夹。这是相对于我们将结构化规范文件的基准文件夹。

swagger:
    config_folder: '%kernel.project_dir%/docs/api/'

假设您有一个这样的Swagger规范

openapi: "3.0.0"
info:
  title: Simple API overview
  version: 2.0.0
paths:
  "/users":
    get:
      operationId: CreateUser
      summary: Create user
      responses:
        '201':
          description: |-
            201 response
  "/orders":
    post:
      operationId: CreateOrder
      summary: Create Order
      responses:
        '201':
          description: |-
            201 response        

这是我们想要的文件夹结构

/docs/api/
     ├── index.yaml
     ├── paths
     │   └── user
     |       └── create-user.yaml
     │   └── order
     |       └── create-order.yaml
     ├── responses
     │   └── created.yaml

根文件是index.yaml。使用index.yaml作为根文件的文件名是一种约定。

以下是文件及其内容的列表

index.yaml

openapi: "3.0.0"
info:
  title: Simple API overview
  version: 2.0.0
paths:
  "$paths"

paths/user/create-user.yaml

"/users":
  get:
    operationId: CreateUser
    summary: Create user
    responses:
      "$responses/created.yaml"

paths/order/create-order.yaml

"/orders":
  post:
    operationId: CreateOrder
    summary: Create Order
    responses:
      "$responses/created.yaml"

paths/responses/created.yaml

'201':
  description: |-
    201 response

如示例所示，为了指定包含的文件夹或文件，我们使用符号$和名称。

• $paths - 包含paths文件夹中的所有.yaml文件（递归）;
• $responses/created.yaml - 包含存储在responses文件夹中的created.yaml文件。

生成Swagger UI

要生成Swagger UI静态文件，请使用控制台命令

bin/console assets:install && bin/console swagger:generate-docs

文件将保存在%kernel.publid_dic%/public/api/index.html文件夹中，并在http://<project>/api/index.html中共享。

贡献

阅读CONTRIBUTING文件。