README

silex-swagger-provider 是一个将 swagger-php 集成到 silex 中的silex服务提供者。此服务提供者添加了基于swagger-php注解生成和暴露swagger定义的路由。然后可以使用 swagger-ui 来使用swagger定义。

安装

使用 composer 安装 silex-swagger-provider。此项目使用 语义化版本控制。

{
    "require": {
        "jdesrosiers/silex-swagger-provider": "~1.0"
    }
}

参数

• swagger.srcDir: swagger-php组件的路径。
• swagger.servicePath: 包含你的swagger注解的类路径。
• swagger.excludePath: 生成注解时需要排除的路径列表，用冒号 : 分隔。
• swagger.apiDocPath: 用于访问swagger定义的URI。默认为 /api/api-docs。
• swagger.prettyPrint: 决定生成的JSON是否为人类可读的格式。
• swagger.cache: 将传递给Symfony 2的 Response::setCache 方法的缓存选项数组。
• swagger.basePath: 您API的URL。如果您的Swagger注解包含basePath，则将覆盖此值。例如: "http://api.example.com/
• swagger.apiVersion: 您API的版本。如果您的Swagger注解包含版本，则将覆盖此值。
• swagger.swaggerVersion: 您API的Swagger版本。如果您的Swagger注解包含swagger版本，则将覆盖此值。
• swagger.resourcePrefix: 将附加到每个资源URI的前缀字符串。默认为 "/"。
• swagger.resourceSuffix: 将附加到每个资源URI的后缀字符串。默认为 ""。

服务

• swagger: Swagger\Swagger 的实例。它用于内部生成swagger定义。你可能不需要直接使用它。

注册

$app->register(new JDesrosiers\Silex\Provider\SwaggerServiceProvider(), array(
    "swagger.srcDir" => __DIR__ . "/vendor/zircote/swagger-php/library",
    "swagger.servicePath" => __DIR__ . "/path/to/your/api",
));

使用

默认提供的以下路由

• GET /api/api-docs: 获取资源列表
• GET /api/api-docs/{service}: 获取特定资源的定义

Swagger定义文件的输出不会在内部进行缓存。相反，创建的路由设计为与HTTP缓存（如浏览器缓存或反向代理）一起工作。您可以使用swagger.cache参数配置如何缓存您的服务。默认情况下，不会进行缓存。有关如何在Symfony中自定义缓存行为的更多信息，请参阅HTTP缓存。以下示例将允许服务定义文件缓存5天。

$app["swagger.cache"] = array(
    "max_age": "432000", // 5 days in seconds
    "s_maxage": "432000", // 5 days in seconds
    "public": true,
)

日志记录

Swagger使用PHP通知和警告来记录它在尝试生成您的API文档时遇到的问题。如果您的silex应用程序有一个logger服务，它也会记录这些问题。

入门指南

以下是一个快速入门的最小示例。它使用jdesrosiers/silex-cors-provider允许我们使用swagger-ui的演示安装，而无需自己搭建。有关如何扩展此示例的详细信息，请参阅swagger-php文档。

• 创建一个至少包含以下依赖的composer.json文件

{
    "require": {
        "jdesrosiers/silex-swagger-provider": "~1.0",
        "jdesrosiers/silex-cors-provider": "~0.1"
    }
}

• 运行composer install
• 创建/web/index.php

<?php

use Swagger\Annotations as SWG;

require __DIR__ . "/../vendor/autoload.php";

/**
 * @SWG\Resource(basePath="http://localhost:8000", resourcePath="/foo")
 */
$app = new Silex\Application();
$app["debug"] = true;

$app->register(new JDesrosiers\Silex\Provider\SwaggerServiceProvider(), array(
    "swagger.srcDir" => __DIR__ . "/../vendor/zircote/swagger-php/library",
    "swagger.servicePath" => __DIR__ . "/",
));

$app->register(new JDesrosiers\Silex\Provider\CorsServiceProvider(), array(
    "cors.allowOrigin" => "http://petstore.swagger.io",
));

/**
 * @SWG\Api(path="/foo", @SWG\Operations(@SWG\Operation(method="GET", nickname="foo")))
 */
$app->get('/foo', function () use ($app) {
    return 'bar';
});

$app->after($app["cors"]);

$app->run();

• 运行服务php -S localhost:8000 -t web web/index.php
• 访问http://petstore.swagger.io/，在顶部输入框中输入http://localhost:8000/api/api-docs，然后点击Explore