README

它做什么？

此捆绑包/插件会解析您的源代码并为您生成的API生成Swagger文档。

它如何工作？

捆绑包包含一个控制器，其中包含2个操作。

第一个操作解析您的源代码并返回JSON
第二个控制器渲染视图以显示Swagger-UI

Swagger-UI使用CDN的资产，因此不包含任何js或css文件！

如何安装？

您可以通过composer安装此捆绑包，或者直接下载git仓库并将其粘贴到您的项目目录中。

需要配置的两件重要事情

路由

您必须配置2个路由才能使其正常工作

    [
        'class' => \Igsem\Docs\Controllers\DocsController::class,
        'methods' => [
            'get' => [
                getenv('SWAGGER_JSON_URI') => 'indexAction',
                '/docs' => 'docsAction',
            ],
        ],
    ],

第一个路由是JSON响应的路由，Swagger需要它来渲染文档。此URL映射到扫描您项目的注释的控制器。

第二个路由是您希望能够访问文档的路由。

我使用一个环境文件进行我的配置，因此第一个路由是我环境文件中的一个参数。原因是JSON响应的URL需要注册在DI中。

DI

捆绑包期望在DI容器中有一个名为swagger的条目。

这里我从.env文件加载配置

'swagger' => [
        'path' => APP_PATH . '/src',
        'host' => getenv('SWAGGER_HOST'),
        'schemes' => explode(',', getenv('SWAGGER_SCHEMES')),
        'basePath' => getenv('SWAGGER_BASEPATH'),
        'version' => getenv('SWAGGER_VERSION'),
        'title' => getenv('SWAGGER_TITLE'),
        'description' => getenv('SWAGGER_DESCRIPTION'),
        'email' => getenv('SWAGGER_EMAIL'),
        'jsonUri' => getenv('SWAGGER_JSON_URI'),
        'exclude' => explode(',', getenv('SWAGGER_EXCLUDE')),
    ],

这里我注册DI

    /**
     * Configure Swagger
     */
    protected function initDocs()
    {
        /** @var PhConfig $config */
        $config = $this->diContainer->getShared('config');
        $this->diContainer->setShared(
            'swagger',
            function () use ($config) {
                return $config->get('swagger')->toArray();
            }

        );
    }

现在，如何将swagger条目放入DI容器由您决定。您可以简单地注册所有值。

这些值是预期和必需的

path - 应该扫描的源目录的路径，例如 APP_PATH. '/src'
host - 您的域名，例如 my-awesome-api.com
schemes [数组] - 支持的方案，例如 http,https（这必须是一个数组）
basePath - URL基本路径，例如 /
version - 您的API版本，例如 0.0.1
title - 您的应用程序标题
description - 您的应用程序描述
email - 联系邮箱
jsonUri - 您配置的JSON响应的URL，例如 /swagger-json

以下值是可选的

exclude [字符串|数组] - 要排除扫描的路径，例如 APP_PATH. '/src/path_to_exclude/' 或 [APP_PATH. '/src/path_to_exclude_1/', APP_PATH. '/src/path_to_exclude_2/']

使用方法

使用方法与标准的Swagger库相同，有关更多信息，请参阅 https://github.com/zircote/swagger-php。

我仅使用基本的Swagger配置，但如果您想扩展它，使用忽略的文件夹等。我建议在基本控制器上添加一个注解，如下所示

/**
 * @SWG\Swagger(
 *     schemes={"http","https"},
 *     host="api.host.com",
 *     basePath="/",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="This is my website cool API",
 *         description="Api description...",
 *         termsOfService="",
 *         @SWG\Contact(
 *             email="contact@mysite.com"
 *         ),
 *         @SWG\License(
 *             name="Private License",
 *             url="URL to the license"
 *         )
 *     ),
 *     @SWG\ExternalDocumentation(
 *         description="Find out more about my website",
 *         url="http..."
 *     )
 * )
 */

class BaseController

!请注意，配置会覆盖注解，因此请仅将其用作扩展！

示例

以下是注释模型的方法


/**
 * @SWG\Definition(required={"email", "name", "password"}, type="object", @SWG\Xml(name="User"))
 */
class User extends Model
{
    /**
     * @SWG\Property(name="id", type="string", description="UUID")
     * @var int
     */
    public $id;

    /**
     * @SWG\Property(name="name", type="string")
     * @var string
     */
    public $name;

    /**
     * @SWG\Property(name="email", type="string")
     * @var string
     */
    public $email;

    /**
     * @SWG\Property(name="password", type="string")
     * @var string
     */
    public $password;
}

以下是一个登录示例控制器

/**
     *
     * @SWG\POST(
     *   path="/login",
     *   summary="Login",
     *   produces={"application/json"},
     *     @SWG\Parameter(
     *     in="formData",
     *     type="string",
     *     name="email",
     *     required=true,
     *     @SWG\Schema(ref="#/definitions/User")
     *   ),
     *     @SWG\Parameter(
     *     in="formData",
     *     type="string",
     *     name="password",
     *     required=true,
     *     @SWG\Schema(ref="#/definitions/User")
     *   ),
     *   @SWG\Response(
     *     response=200,
     *     description="Returns a JWT token for authorization"
     *   ),
     *   @SWG\Response(
     *     response=404,
     *     description="Not found User, Invalid password"
     *   ),
     *   @SWG\Response(
     *     response=422,
     *     description="Validation of formData failed"
     *   )
     * )
     * @return string
     */
    public function loginAction()
    {
        ...

缺少什么

我很快就设计了这个库，没有时间去编写测试或者用更多的例子来测试它。这个库应该可以正常工作，我在我的项目中正在使用它。任何人都可以根据需要自由使用或修改它。如果有人感兴趣，我很乐意收到一些pull requests :)。

igsem / phalcon-swagger

维护者

详细信息